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Introduction 


This manual, Supplemental Documentation, is part of a collection of manuals called the 
NeXT Developer’s Library, the illustration on the first page shows the complete set of 
manuals in this Library. 

Primarily, Supplemental Documentation contains a series of papers from Adobe Systems 
Incorporated, describing various aspects of the PostScript® system. The manual also 
contains the Rich Text Format® Specification from Microsoft Corporation. 

The specification for one of the file formats used with NeXT computers—TIFF—isn’t 
contained in this manual. If you’re interested in learning more about the TIFF format, the 
Aldus TIFF Developer’s Toolkit (which includes the Tag Image File Format Specification 
and supplementary documentation, as well as sample files and utility software on disk) is 
available from Aldus Corporation. For more information, contact the Aldus Developers 
Desk at (206)628-6593. 
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1. INTRODUCTION 

This document describes a standard interchange format for communicating font metric 
information to people and programs. The format is ASCII encoded (for both human and 
machine readability), machine independent, and extensible. Files in this format are known 
as Adobe® Font Metrics (AFM) files and are available for all of Adobe Systems’s 
PostScript fonts. 


2. PARSING DETAILS 

Each AFM file contains the information for one PostScript printer font. The file begins with 
global information pertaining to the font as a whole, followed by sections with character 
metrics, kerning data (optional) and composite character data (optional). The file format is 
line-oriented, each line beginning with a property (key) name, followed by the values for 
that property. Keys and values are separated by one or more white space characters (space 
or tab). 

The format is: 

Key value value ... 

Key names are case-sensitive. All keys beginning with a capital letter are reserved for use 
by Adobe Systems; user-defined non-standard entries should begin with a lowercase letter. 
The Adobe Systems standard keys are detailed below, but other keys are allowed and 
should be ignored by programs not recognizing them. 

Values will be one of the following: string, name, number, integer or boolean. 

• Strings are terminated by the end of line. 

• Names are similar to strings except that they may not contain any white space characters; 
they are terminated by white space characters or by a special termination character (see 
section on “Character Metrics’’ below). 

• Numbers, integers and booleans are separated by white space characters, which may be 
space, newline, or tab. 

• A number can be either a real number or an integer, and both must be allowed for. 

• A boolean is either the value true or false. 
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2.1 COMMENTS 


Comments may be present in a font metric file. They are introduced by the keyword 
Comment, and are terminated by the end of line. Lines should be no longer than 255 
characters under any circumstances. 

Comment string 

The text is arbitrary, and should be ignored. 


3. FILE STRUCTURE 

An AFM file has several sections, each of which is delimited by a Start and End keyword. 
The main section contains a “header” of global font information, and each of the other 
sections of the file is hierarchically one level down from the main section. 

StartFontMetrics version 
EndFontMetrics 

These comments delimit the entire font metrics file. The StartFontMetrics line should be 
the first line in the file, and the EndFontMetrics keyword should be the last line in the file. 

3.1 GLOBAL FONT INFORMATION 

The following global font keys are the same as those in the top level or Fontlnfo 
subdictionary of an Adobe Systems PostScript font dictionary. Their meanings are 
described in the chapter on fonts in the PostScript Language Reference Manual. Please note 
that although some of the keys in the PostScript Fontlnfo subdictionary begin with a 
lowercase letter (e.g., isFixedPitch, version) all keys listed here begin with uppercase 
letters to distinguish them as keys reserved for use by Adobe Systems. All numeric values 
are in the character coordinate system (1000 units per em). 

FontName string 

Name of the font as presented to the PostScript findfont operator. 

Example: Garamond-Light. 

FullName string 

The full text name of the font. Example: ITC Garamond Light. 

FamilyName string 

The name of the “font family” to which the font belongs. 

Example: ITC Garamond. 

Weight string 

Weight of the font. Example: Roman, Bold, Light, etc. 

ItalicAngle number 

Angle (in degrees counter-clockwise from the vertical) of the dominant vertical strokes of 
the font. 

Example: -12. 
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IsFixedPitch boolean 

If boolean is true, this indicates that the font is a fixed pitch (monospaced) font. A value 
of false indicates a proportionally spaced font. 

FontBBox llx lly urx ury 

Four numbers giving the lower left comer and the upper right comer of the font bounding 
box. Note: the bounding box given here is that of the flattened paths, not the Bezier curve 
descriptions. These values are all integers, and should be rounded off if necessary. 

UnderlinePosition number 

Distance from the baseline for centering underlining strokes. 

UnderlineThickness number 

This is the stroke width for underlining, expressed in character coordinate space 
(proportional to the font characters). It should be adjusted for point size by any application 
wishing to perform underlining. 

Version string 

Font version identifier. Matches the string found in the Fontlnfo dictionary of the font itself. 

Notice string 

Font name trademark or copyright notice. 

EncodingScheme string 

String indicating the default encoding vector for this font. The most common one is 
AdobeStandardEncoding. Special fonts may simply state FontSpecific. 

CapHeight number 

Top of capital H, measured in character coordinate system. 

XHeight number 

Top of lower case x, measured in character coordinates. 

Ascender number 

Top of lower case d. 

Descender number 

Bottom of lower case p. 

INDIVIDUAL CHARACTER METRICS 

Each character’s metrics consists of a list of keys and values separated by semicolons; the 
metrics for a given character will always be contained in one line. The characters are sorted 
by numerically ascending character code. Unencoded characters follow the encoded 
characters and are identified by character codes of -1. 

Example: A character metric data line might look like this: 

C 102; WX 333; N f; B 21 0 382 685; L i fi; L I fl; 
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StartCharMetrics integer 
EndCharMetrics 

These comments introduce (and conclude) the character metrics section of the file. The 
integer value indicates how many individual characters to expect. 

C integer 

Decimal value of default PostScript character code (-1 if unencoded). 

WX number 

Character width in x (y is 0). 

W number x numbery 

Character width vector (x,y) 

N name 

PostScript character name. 

B llx lly urx ury 

Character bounding box where llx, lly, urx, and ury are all numbers. 

L successor ligature 

Ligature sequence where successor and ligature are both names. The current character may 
join with the character named successor to form the character named ligature. Note that 
characters may have more than one such entry. (See example above.) 


5. KERNING DATA 

The kerning data section is optional; it may or may not be present for a given font. The 
section is surrounded by the lines StartKernData and EndKernData. Kerning data is 
supplied in two forms: track kerning and pair-wise kerning. Track kerning is applied to all 
characters uniformly whereas pair-wise kerning is applied to specific character pairs. Track 
kerning and pair-wise kerning may be used independently or together (i.e., it is possible to 
apply track kerning to a line of text and then to apply pair-wise kerning on top of that). The 
two forms of kerning data are treated as subsections within the kerning data section and 
both sections need not be present. 

StartKernData 

EndKernData 

These comments introduce (and conclude) the kerning section of the file. 

5.1 TRACK KERNING 

The track kerning data is surrounded by the lines: 

StartTrackKern integer 
EndTrackKern 

Where integer indicates how many different sets of track kerning data are present. 
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Normally track kerning is provided in different degrees of tightness. Within a track (a 
degree of tightness), the amount to decrease (or possibly increase) the amount of space 
between characters increases (or possibly decreases) with the point size of the font (e.g., for 
tight track kerning, the amount to decrease the space between characters at 6 point might 
be 0.1 points and at 72 point it might be 3.78 points). 

The data itself begins with the key TrackKern and is followed by the track kerning 
information: 

TrackKern degree min-ptsize min-kern max-ptsize max-kern 

The degree is an integer where increasingly negative degrees represent tighter track kerning 
and increasingly positive degrees represent looser track kerning, min-pt-size, min-kern- 
amt , max-pt-size and max-kern-amt are all numbers. Since the track kerning is a linear 
function, the minimum and maximum cut-off values (point sizes) are provided along with 
the amount to track kem by at the point size. The kerning amounts are given relative to the 
point size. From those 4 values, the track kerning function can be derived. The track 
kerning function is a linear function. The equation for the line can be determined from the 
data provided and, therefore, the track kerning values for any point size can be determined. 
The track kerning values for any point size below/above the minimum/maximum point size 
are constant (the minimum kerning amount/maximum kerning amount). 

In general the track kerning function is as follows: 

TrackKern degree pg kg pj k^ 

Where x = current point size 

Where kj = max-kern-amt, kg = min-kem-amt 

Where P j = max-pt-size, Pq = min-pt-size 


f(x) = 

k 0 

fOVX < Pq 

f(x) = 

( kj-k Q ) * x + (k 0 *pj-kj*p0 ) 

for Pq < x 


(Pj-Po') (p l~Po ) 


f(x) = 

k l 

for x > pj 


See the last section of this document for a good example of these keywords in use. 
Below is a sample of text printed using these track kerning values. 
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Figure 1: 

no kerning 
light kerning 
medium kerning 
tight kerning 


no kerning 
light kerning 
medium kerning 
tight kerning 


no kerning 
light kerning 
medium kerning 
tight kerning 


Track Kerning 

6 pt ™ ■■. .. ■» 

An illustration of how track kerning works. 

An illustration of how track kerning works. 

An illustration of how track kerning works. 

An illustration of how track kerning works. 

12 pt . . . 

An illustration of how track kerning works. 

An illustration of how track kerning works. 

An illustration of how track kerning works. 

An illustration of how track kerning works. 

18 pt ——————- 

An illustration of how track kerning works. 
An illustration of how track kerning works. 
An illustration of how track kerning works. 

An illustration of how track kerning works. 
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5.2 PAIR-WISE KERNING 


The pair-wise kerning data is surrounded by the lines: 

StartKernPairs integer 
EndKernPairs 

Where integer indicates how many pairs to expect. 

There will be one kerning pair per line. Each line will begin with a keyword of the form KP 
or KPX. 

KP name-i name 2 number x number y 

Name of the first character in the kerning pair followed by the name of the second character 
followed by the kerning vector specified as an (x,y) pair. The kerning vector is the amount 
to move the second character by relative to the first character to position it properly. The 
kerning vector is specified in the character coordinate system. In order to use this vector it 
is necessary to transform it into user space and scale it by the point size in use. The best 
way to do this is to use the FontMatrix entry in the current font dictionary. 

KPX name 1 name 2 number x 

Name of the first character in the kerning pair followed by the name of the second character 
followed by the kerning amount in the x direction (y is zero). The kerning amount is 
specified in the units of the character coordinate system. 

A character pair kerning line might look like this: 

KPX V A-129 

Below is an example of pair-wise kerning applied to 100 point characters: 

Figure 2: Pair-wise kerning 


VA VA 

-09 

Characters printed without kerning Pair-wise kerning applied 


6. COMPOSITE CHARACTER DATA 

The composite character data section is also optional. Composite characters are new 
characters that are made up of characters already existing in the font, such as accented 
characters. Character metric information for composite characters is found in the Character 
Metrics section of the AFM file. Although most PostScript fonts available from Adobe 
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Systems include a rather extensive set of composite characters, some applications may wish 
to generate their own. This section provides the data necessary for accurate positioning of 
the individual pieces. All units are expressed in the 1000 unit-per-em character coordinate 
system. 

StartComposites integer 
EndComposites 

Where integer indicates how many pairs to expect. 

The data for each composite character is represented as a list of keys and values separated 
by semicolons. Each composite character gets one line of description. The standard keys 
are: 

CC name integer 

The composite character name followed by the number of parts that make up the composite. 

PCC name deltax deltay 

One of the parts of the composite character. The character name is given followed by the x 
and y displacement from the origin. 

A composite character line might look like this: 

CC Aacute 2; PCC A 0 0; PCC acute 194 214; 


Figure 3: Example of positioning for a composite character 



Positioning of Positioning of Composite Aacute 

character A character acute 
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7. EXAMPLE FILE 


The following is an example of an AFM file for Times Roman, although some of the data 
have been omitted to keep it short. 

StartFontMetrics 2.0 

Comment Copyright (c) 1984 Adobe Systems Incorporated. 

Comment All Rights Reserved. 

FontName Times-Roman 
FullName Times Roman 
FamilyName Times 
Weight Medium 
ItalicAngle 0.0 
IsFixedPitch false 
UnderlinePosition -98 
UnderlineThickness 54 
Version 001.000 

Notice Times is a trademark of Allied Corporation. 

EncodingScheme AdobeStandardEncoding 

FontBBox -167 -252 1004 904 

CapHeight 673 

XHeight 445 

Descender-219 

Ascender 686 

StartCharMetrics 210 

C 32 ; WX 250 ; N space ; B 0 0 0 0 ; 

C 33 ; WX 333 ; N exclam ; B 128 -17 240 673 ; 

C 34 ; WX 408 ; N quotedbl; B 46 445 313 685 ; 

C 35 ; WX 500 ; N numbersign ; B 20 -17 481 673 ; 

C 36 ; WX 500 ; N dollar; B 45 -92 456 726 ; 

C 37 ; WX 833 ; N percent; B 63 -36 771 655 ; 

lines omitted for brevity -- 
C 101 ; WX 444 ; N e ; B 24 -17 416 469 ; 

C 102 ; WX 333 ; N f; B 21 0 382 685 ; L i fi; LI fl; 

C 103 ; WX 500 ; N g ; B 24 -220 469 468 ; 

C 104 ; WX 500 ; N h ; B 11 0 487 686 ; 

C 105 ; WX 278 ; N i; B 25 0 255 685 ; 

C 106 ; WX 278 ; N j; B -56 -217 205 685 ; 

C 107 ; WX 500 ; N k ; B 7 0 496 686 ; 

...-- lines omitted for brevity ~ 

C 248 ; WX 278 ; N Islash ; B 0 0 283 685 ; 

C 249; WX 500 ; N oslash ; B 30 -104 469 566 ; 

C 250 ; WX 722 ; N oe ; B 30 -10 684 462 ; 

C 251 ; WX 500 ; N germandbls ; B 13 0 468 686 ; 

C -1 ; WX 722 ; N Aacute ; B 22 0 702 873 ; 

C -1 ; WX 722 ; N Acircumflex ; B 22 0 702 875 ; 

C -1 ; WX 722 ; N Adieresis ; B 22 0 702 819 ; 

...-- lines omitted for brevity -- 
EndCharMetrics 
StartKernData 
StartTrackKern 3 
Comment Light kerning 
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TrackKern -1 14 0 72-1.89 
Comment Medium kerning 
TrackKern -2 8 0 72 -3.2 
Comment Tight kerning 
TrackKern -3 6 -.1 72 -3.78 
EndTrackKern 
StartKernPairs 2 
KPX V A -129 
KPX A Y -92 
EndKernPairs 
EndKernData 
StartComposites 1 

CC Aacute 2; PCC A 0 0; PCC acute 194 214; 

EndComposites 

EndFontMetrics 
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1. INTRODUCTION 

This document describes Adobe Systems’s character bitmap distribution format. The 
format is intended to be easily understood by both humans and computers. The format 
described in this document is subject to change without prior notification. 

1.1 TAPE FORMAT 

These character bitmaps are typically distributed on magnetic tape. Each tape is 1600 BPI, 
nine track, unlabeled, and contains two or more files. Each file is followed by an EOF mark. 
The last file on the tape is followed by two EOF marks. Physical records contain 512 bytes. 
The last physical record in a file (preceding an EOF mark) may contain fewer than 512 
bytes. 

Each file is encoded in the printable characters (octal 40 through 176) of USASCII plus 
carriage return and linefeed. Each file consists of a sequence of variable-length lines. Each 
line is terminated by a carriage-return (octal 015) and line-feed (octal 012). The first file on 
the tape is the Adobe Systems Copyright notice. Following files are font files. The format 
of font files is described in the following sections. 

Note: 

Font tapes may also be obtained in UNIX tar format. Be sure to specify tar format 
if desired. No other tape formats are currently supported by Adobe Systems. 

1.2 FILE FORMAT 

Character bitmap information is distributed in an USASCII encoded, human readable form. 
The information about a particular family and face at one size and orientation is contained 
in one file. The file begins with information pertaining to the face as a whole, followed by 
the information and bitmaps for the individual characters. 

A font bitmap description file has the following general form, where each item is contained 
on a separate line of text in the file. Items on a line are separated by spaces. 

GLOBAL HEADER INFORMATION 

• The word STARTFONT followed by a version number indicating the exact file format 
used (for example, 2.1) 

• One or more lines beginning with the word COMMENT. These lines may be ignored by 
any program reading the file. 

• The word FONT followed by the family name and the face name separated by a 
hyphen. This should exactly match the PostScript outline font name. 
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• The word SIZE followed by the point size of the characters, the x resolution, and the y 
resolution of the device for which these characters were intended. All are represented 
as integers. 

• The word FONTBOUNDINGBOX followed by the width in x, height in y, and the x 
and y displacement of the lower left comer from the origin. (See the examples in 
section 1.3). These are all integers. 

• Optionally the word STARTPROPERTIES followed by the number of properties (p) 
that follow. This is a recent addition to the format. Within the properties list, there may 
be p lines consisting of a word for the property name followed by either an integer or 
string surrounded by ASCII double quotes (ASCII octal 042). Internal quote characters 
are indicated (or “quoted”) by using two in a row. The property section, if it exists, is 
terminated by ENDPROPERTIES 

THE INDIVIDUAL CHARACTER INFORMATION 

The character section is introduced by the word CHARS followed by the number of 

character segments (c) that follow. This is an integer value. Error checking is recommended 

at the end of the file, to make sure that c characters were actually read and processed. Each 

of the c characters is then represented by the following: 

• The word STARTCHAR followed by up to 14 bytes (no blanks) containing the name of 
the glyph. This should correspond to its name in the PostScript outline font’s encoding 
vector. 

• The word ENCODING followed by a positive integer representing the Adobe Standard 
Encoding value. If the character is not a member of the Adobe Standard Encoding, 
ENCODING is followed by -1 and optionally by another integer specifying the glyph 
index. 

• The word SWIDTH followed by the scalable width in x and y of character. Scalable 
widths are in units of l/1000th of the size of the character, and correspond to the widths 
found in AFM files (for outline fonts). If the size of the character is p points, the width 
information must be scaled by p/1000 to get the width of the character in printer’s points. 
This width information should be considered as a vector indication the position of the 
next character’s origin relative to the origin of this character. To convert the scalable 
width to the width in device pixels, multiply SWIDTH times p/1000 times r! 72 where r 
is the device resolution in pixels per inch. The result is a real number giving the ideal 
print width in device pixels. The actual device width must of course be an integral 
number of device pixels and is given in the next entry. 

• The word DWIDTH followed by the width in x and y of the character in device units 
(pixels). Like the SWIDTH, this width information is a vector indicating the position of 
the next character’s origin relative to the origin of this character. 

• The word BBX followed by the width in x (BBw), height in y (BBh) and x and y 
displacement (BBxoff, BByoff) of the lower left comer of the bitmap from the origin of 
the character. 

• The word BITMAP. This introduces the hexadecimal data for the character bitmap. 

• From the BBX value for h , find h lines of hex-encoded bitmap, padded on the right with 
zero’s to the nearest byte (i.e., multiple of 8). Hex data can be turned into binary by 
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taking two bytes at a time, each of which represents 4 bits of the 8-bit value. For 
example, the byte 01101101 is two hex digits: 6 (0110 in hex) and D (1101 in hex). 

• The word ENDCHAR. 

• The entire file is terminated with the word ENDFONT. If this is encountered before c 
characters have been read, it is an error condition. 

METRIC INFORMATION 

The font metrics include both the scalable width (really the width of the corresponding 
printer font character) and the character width of the screen font glyph, expressed in pixels. 
The scalable width is more accurate, and can be used by applications for keeping track of 
roundoff error and compensating in placement. 

The following figures best illustrate the bitmap format and character metric information: 


STARTCHARj 
ENCODING 106 
SWIDTH 355 0 
DWIDTH 8 0 
BBX 9 22 -2 -6 


The Bounding Box is 
expressed differently than 
other PostScript language 
files; the first two are the 
width and height , the second 
two are the offsets in x and y. 
This can bee seen in the 
illustration at right. 

The character width from the 
origin (between + indicators) 
is 8 pixels, which has nothing 
to do with the actual bits, but 
is how far the current point 
moves after rendering the 
character. 


BBxoff 



The bounding box of the bitmap character can be used to predict how much data to read in 
the BITMAP section; the first two numbers give the width and height of the bitmap, and 
correspond exactly to how much data is supplied. The offset then allows positioning 
without repeating lots of white bits (look at the following quoteright character, which 
doesn’t have very many bits, but is located far above the baseline. That is what the offset 
fields are for): 


©1989 Adobe Systems Incorporated. All rights reserved. 
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BBxoff 


STARTCHAR quoteright 
ENCODING 39 
SWIDTH 223 0 
DWIDTH 5 0 
BBX45 2 12 

Here the actual bitmap is 
much smaller, and the offset 
(2 in jc, 12 in y) positions the 
glyph with respect to its 
origin. These bitmaps are 
actually both from an italic 
font; notice that the character 
width of the quoteright leaves 
the origin still to the left of 
the actual bits after the 
character is drawn. Since all 
the characters are slanted, the 
next one will not interfere. 


^ BBw^ 



The bitmap itself is started by the BITMAP keyword and finished with the ENDCHAR 
keyword. It is best to “predict” the amount of data needed (using the BBX information) and 
use the ENDCHAR as an error-checking method: if you have consumed what you think is 
the appropriate amount of data, the very next thing in the file should be ENDCHAR. If not, 
either your parser is in error or the file is not complete (or is incorrect). 

The bitmap itself is represented as hexadecimal digits, where each row corresponds to one 
row of the character bitmap. The bits are padded out to the nearest byte boundary with 0’s, 
and the BBX bounding box information should be carefully consulted to determine how to 
extract the data. 


6 


©1989 Adobe Systems Incorporated. All rights reserved. 




The following is an abbreviated example of a bitmap file containing the specification of two 
characters (the j and quoteright from the previous examples): 


STARTFONT 2.1 

COMMENT This is a sample font in 2.1 format. 
FONT Helvetica-BoldOblique 
SIZE 8 200 200 

FONTBOUN DING BOX 9 24 -2 -6 
STARTPROPERTIES 2 
MinSpace 4 

Copyright "Copyright (c) 1987 Adobe Systems, Inc." 
ENDPROPERTIES 
CHARS 2 
STARTCHAR j 
ENCODING 106 
SWIDTH 355 0 
DWIDTH 8 0 
BBX 9 22 -2 -6 
BITMAP 
0380 
0380 
0380 
0380 
0000 
0700 
0700 
0700 
0700 
0E00 
0E00 
0E00 
0E00 
0E00 
1C00 
1C00 
1C00 
1C00 
2C00 
7800 
F000 
E000 

ENDCHAR 

STARTCHAR quoteright 

ENCODING 39 

SWIDTH 223 0 

DWIDTH 5 0 

BBX45 2 12 

BITMAP 

70 

70 

60 

EO 

CO 

ENDCHAR 

ENDFONT 


©1989 Adobe Systems Incorporated. All rights reserved. 
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1 ABOUT THIS MANUAL 


This manual provides the application programmer with descrip¬ 
tions of Client Library procedures and conventions; these con¬ 
stitute the programming interface to the Display PostScript® sys¬ 
tem. The sections of the manual are listed below: 

• Section 2 introduces the Client Library and provides a 
diagram of its relationship to the Display PostScript sys¬ 
tem. 

• Section 3 provides a brief overview of the Client Library; 
describes the phases of an application program interacting 
with the Display PostScript system; introduces the C header 
files that represent the Client Library interface; and dis¬ 
cusses the use of wrapped procedures. 

• Section 4 describes the basic concepts an application pro¬ 
grammer needs to know before writing a simple application 
for the Display PostScript system. 

• Section 5 discusses call-back procedures of various kinds, 
including text and error handlers. 

• Section 6 contains advanced Client Library concepts in¬ 
cluding context chaining, encoding and translation, buffer¬ 
ing, application/context synchronization, and forked con¬ 
texts. 

• Section 7 provides programming tips and summarizes notes 
and warnings. 

• Section 8 lists and documents an application program that 
illustrates how to communicate with the Display PostScript 
system using the Client Library. 

• Section 9 documents the basic Client Library data struc¬ 
tures and procedures found in dpsclient.h. 

• Section 10 describes the single-operator procedures that 
implement PostScript® operators and lists the dpsops.h 
header file in which they are declared. 

• Section 11 describes the dpsfriends.h header file and its 
support of C-callable procedures produced by the pswrap 
translator. 

• Appendix A lists changes to the manual since the previous 
version. 
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• Appendix B provides an example error handler for the X 
Window System™ implementation of the Display 
PostScript system. 

• Appendix C describes how an application can recover from 
PostScript language errors and provides an example of an 
exception handler. 

For more information about the PostScript language, see the 
PostScript Language Reference Manual and PostScript Lan¬ 
guage Extensions for the Display PostScript System. For more 
information about using the pswrap translator to embed 
PostScript language code in C programs, see the pswrap Refer¬ 
ence Manual. 

1.1 SYSTEM-SPECIFIC DOCUMENTATION 

The term "system specific" is used throughout this manual. It 
refers to areas of the Client Library implementation that are 
necessarily customized to fit a given machine and operating- 
system environment. The Client Library Reference Manual 
describes those aspects of the Client Library that are common to 
all Display PostScript system implementations. 

You will find notes and comments in this manual alerting you to 
system-specific issues. For more information about these system- 
specific aspects of your Client Library implementation, see the 
documentation provided by your Display PostScript system ven¬ 
dor. 

1.2 TYPOGRAPHICAL CONVENTIONS 

The typographical conventions used in this manual are as fol¬ 
lows: 
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Item 

Example of Typographical Style 

file 

dpsclient.h 

variable, typedef, code fragment 

‘ctxf, ‘DPSContextRec’, ‘DPSrectstroke(ctxt, 0.0, 0.0,10.0,20.0)’ 

procedure 

DPSSetContext 

PostScript operator rectfill 


new term 

“A wrapped procedure (wrap for short) consists of 
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2 ABOUT THE CLIENT LIBRARY 


The Client Library is the application programmer’s link to the 
Display PostScript system, which makes the imaging power of 
the PostScript interpreter available for online displays as well as 
for printing. An application program can display text and images 
on the user’s screen by calling Client Library procedures. These 
procedures are written with a C language interface. They 
generate PostScript language code and send it to the PostScript 
interpreter for execution, as shown in Figure 1. 

Figure 1 The Client Library Link to the Display PostScript System 



Application programmers can customize and optimize their ap¬ 
plications by writing PostScript language programs. The pswrap 
translator, described in the pswrap Reference Manual, produces 
application-defined PostScript language programs with C- 
callable interfaces. 
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Note: In this manual, the terms “input” and “output” apply to 
the execution context in the PostScript interpreter, not to the ap¬ 
plication. An application “sends input” to a context and 
“receives output” from a context. This usage prevents the am¬ 
biguity that would otherwise exist, since input with respect to the 
context is output with respect to the application, and vice versa. 
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3 OVERVIEW OF THE CLIENT LIBRARY 


The Client Library is a collection of procedures that provide an 
application program with access to the PostScript interpreter. 
The Client Library includes procedures for creating, communi¬ 
cating with, and destroying PostScript execution contexts. A 
context consists of all the information (or “state”) needed by the 
PostScript interpreter to execute a PostScript language program. 
In the Client Library interface, each context is represented by a 
‘DPSContextRec’ data structure pointed to by a ‘DPSContext’ 
handle. PostScript execution contexts are described in PostScript 
Language Extensions for the Display PostScript System. 

To the application programmer, it appears that Client Library 
procedures directly produce graphical output on the display. In 
fact, these procedures generate PostScript language statements 
and transmit them to the PostScript interpreter for execution; the 
PostScript interpreter then produces graphical output that is dis¬ 
played by device-specific procedures in the Display PostScript 
system. In this way, the Client Library makes the full power of 
the PostScript interpreter and imaging model available to a C 
language program. 

The recommended way of sending PostScript language code to 
the interpreter is to call wrapped procedures generated by the 
pswrap translator; these procedures are described in Section 3.3. 
For simple operations, an application program can send 
PostScript language fragments to the interpreter by calling 
single-operator procedures — each one the equivalent of a 
single PostScript operator — as described in Section 10. It is 
also possible for an application program to send PostScript lan¬ 
guage programs as ASCII text, as if to a laser printer with a 
PostScript interpreter. This technique can be used for develop¬ 
ment and debugging or for displaying PostScript language code 
imported by the application — for instance, from an EPS file. 

3.1 PHASES OF AN APPLICATION 

Here is how a typical application program, written in C, uses the 
Client Library in the different phases of its operation: 
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Initialization. First, the application establishes communication 
with the Display PostScript system. Then it calls 
Client Library procedures to create a context for 
executing PostScript language programs. It also 
performs other window-system-specific in¬ 
itialization. Some higher-level facilities, such as 
toolkits, do all of this initialization automati¬ 
cally. 

Execution. Once an application is initialized, it displays text 
and graphics by sending PostScript language 
programs to the interpreter. These programs may 
be of any complexity from a single-operator pro¬ 
cedure to a program that previews a full-color 
illustration. The Client Library sends the 
programs to the PostScript interpreter and 
handles the results received from the interpreter. 

Termination. When the application is ready to terminate, it 
calls Client Library procedures to destroy its 
contexts, free their resources, and end the com¬ 
munication session. 

3.2 HEADER FILES 

The Client Library procedures that an application can call are 
defined in C header files, also known as include files or interface 
files. There are four Client Library-defined header files and one 
or more system-specific header files. The Client Library inter¬ 
face represented by these header files may be extended in a given 
implementation, but the extensions are compatible with the 
definitions given in this manual. 

• dpsclient.h provides support for managing contexts and 
sending PostScript language programs to the interpreter. It 
supports applications as well as application toolkits. Al¬ 
ways present. 

• dpsfriends.h provides support for wrapped procedures 
created by pswrap as well as data representations, conver¬ 
sions, and other low-level support for context structures. 
Always present. 

• dpsops.h provides the single-operator procedures that re¬ 
quire an explicit context parameter. Optional; at least one 
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single-operator header file must be present; that is, 
dpsops.h or psops.h or both. 

• psops.h provides the single-operator procedures that im¬ 
plicitly derive their context parameter from the current con¬ 
text. Optional; see dpsops.h. 

• One or more system-specific header files provide support 
for context creation. These header files may also provide 
system-specific extensions to the Client Library, such as 
additional error codes. 

3.3 WRAPPED PROCEDURES 

The most efficient way for an application program to send 
PostScript language code to the interpreter is to use the pswrap 
translator to produce wrapped procedures — that is, PostScript 
language programs that are callable as C procedures. A wrapped 
procedure (wrap for short) consists of a C language procedure 
declaration enclosing a PostScript language body. There are 
several advantages to using wraps: 

• Complex PostScript programs can be invoked by a single 
procedure call, avoiding the overhead of a series of calls to 
single-operator procedures. 

• You can insert C arguments into the PostScript language 
code at runtime instead of having to push the C arguments 
onto the PostScript operand stack in separate steps. 

• Wrapped procedures can efficiently produce custom graph¬ 
ical output by combining operators and other elements of 
the PostScript language in a variety of interesting ways. 

• The PostScript language code sent by a wrapped procedure 
is interpreted faster than ASCII text. 

An application developer prepares a PostScript language 
program for inclusion in the application by writing a wrap and 
passing it through the pswrap translator. The output of pswrap is 
a procedure written entirely in the C language. It contains the 
PostScript language body as data. This body has been compiled 
into a binary object sequence (an efficient binary encoding), with 
placeholders left for arguments to be inserted at execution time. 
The translated wraps can then be compiled and linked into the 
application program. 
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When a wrapped procedure is called by the application, the 
procedure’s arguments are substituted for the placeholders in the 
PostScript language body of the wrap. 

Example: A wrap that draws a black box could be defined as 
follows: 

defineps PSWBIackBox(float x, y) 
gsave 

0 0 0 setrgbcolor 
x y 72 72 rectfill 
grestore 
endps 

pswrap produces a procedure that can be called from a C lan¬ 
guage program as follows (the values shown are merely 
examples): 

PSWBIackBox(12.32, -56.78); 

This procedure replaces the x and y operands of rectfillwith the 
corresponding procedure arguments, producing executable 
PostScript language code: 

gsave 

0 0 0 setrgbcolor 
12.32 -56.78 72 72 rectfill 
grestore 

Any wrapped procedure works the same way as the above ex¬ 
ample: the arguments of the C language procedure must cor¬ 
respond in number and type to the operands expected by the 
PostScript operator(s) in the body of the wrap. For instance, a 
procedure argument declared to be of type ‘float’ corresponds to 
a PostScript real object; an argument of type ‘char *’ cor¬ 
responds to a PostScript string object; and so on. 

The normal outcome of calling a wrapped procedure is the trans¬ 
mission of PostScript language code to the interpreter for execu¬ 
tion, normally resulting in display output. The Client Library 
may also provide means, on a system-specific basis, to divert 
transmission to another destination, such as a printer or a text 
file. 

For more information about how wraps are defined and used, see 
the pswrap Reference Manual. 
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4 BASIC CLIENT LIBRARY FACILITIES 


This section introduces the concepts needed to write a simple 
application program for the Display PostScript system, includ¬ 
ing: 


• Creating a context. 

• Sending code and data to a context. 

• Destroying a context. 

The basic facilities provided by the Client Library to application 
programs are described in this section. 

The Client Library procedures and data structures that are 
referred to in this introduction are documented in the following 
places: 

Section 9. Header file dpsclient.h. Provides general support 
for contexts; includes procedures that send 
PostScript language programs for execution and 
receive results. General applications and appli¬ 
cation support software (that is, toolkits) make 
use of this header file. 

Section 10. Header files dpsops.h and psops.h. Declarations 
for single-operator procedures. 

System-specific documentation. 

Support for creating context records. An ex¬ 
ample of context creation is provided in Section 
4.3. 

4.1 CONTEXTS AND CONTEXT DATA STRUCTURES 

An application creates, manages, and destroys one or more con¬ 
texts. A typical application creates a single context in a single 
private VM (space). It then sends PostScript language code to 
the context to display text, graphics, and scanned images on the 
screen. 

The context is represented by a record of type ‘DPSContextRec’; 
see Section 9.1 for the type definition. A handle to this record 
— a pointer of type ‘DPSContext’ — is passed explicitly or 
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implicitly with every Client Library procedure call. In essence, 
to the application programmer, the ‘DPSContext’ handle is the 
context. 

A context can be thought of as a destination to which PostScript 
language code is sent. The destination is set when the context is 
created. In most cases, the code draws graphics in a window or 
specifies how a page will be printed. Other possible destinations 
include a file (for execution at a later time) or the standard out¬ 
put; multiple destinations are permitted. The execution by the 
interpreter of PostScript language code sent to a context may be 
immediate or deferred, depending on which context creation pro¬ 
cedure was called and on the setting of certain ‘DPSContextRec’ 
variables. 

4.2 SYSTEM-SPECIFIC CONTEXT CREATION 

The system-specific interface 1 contains, at minimum, procedures 
for creating the ‘DPSContextRec’ record for the given im¬ 
plementation of the Client Library. The system-specific interface 
also provides support for certain extensions to the Client Library 
interface, such as additional error codes. 

Every context is associated with a system-specific object such as 
a window or a file. The context is created by calling a procedure 
in the system-specific interface. Once the context has been 
created, however, a set of standard Client Library operations 
may be applied to it; these operations, including context destruc¬ 
tion, are defined in the standard header file dpsclient.h. 

4.3 EXAMPLE OF CONTEXT CREATION 

Context creation facilities are necessarily system specific. This is 
because they often need data objects that represent system- 
specific entities such as windows and files. However, most con¬ 
text creation facilities share a number of common attributes. In 
the text that follows, procedure parameters that are common to 
most systems are described in some detail, while system-specific 
parameters are listed without further discussion. The procedures 


'in Adobe’s sample XI 1/DPS extension implementation, the system-specific 
header file is dpsXclient.h. 
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described here were designed for the X Window System. They 
provide an example of an actual system implementation while at 
the same time demonstrating basic functions that all window 
systems must provide for context creation. 

The creation of a ‘DPSContextRec’ data structure is usually part 
of application initialization. Contexts persist until they are 
destroyed; see DPSDestroyContext and DPSDestroySpace in 
Section 9.2. 


/* EXAMPLE CONTEXT CREATION FOR THE X WINDOW SYSTEM V 
DPSContext XDPSCreateSimpleContext(dpy, drawable, gc, x, y, textProc, errorProc, space) 
Display *dpy; 

Drawable drawable; 

GC gc; 
int x, y; 

DPSTextProc textProc; 

DPSErrorProc errorProc; 

DPSSpace space; 

typedef void (*DPSTextProc)( /* 

DPSContext ctxt, 
char *buf, 

long unsigned int count 7); 

typedef void (*DPSErrorProc)( /* 

DPSContext ctxt, 

DPSErrorCode errorCode, 
long unsigned int argl, arg2 7); 


XDPSCreateSimpleContext is a system-specific procedure that 
creates an execution context in the PostScript interpreter. The 
arguments ‘dpy\ ‘gc’, ‘x\ and ‘y’ have specific uses in the X 
Window System; discussion of these arguments is beyond the 
scope of this manual. The ‘drawable’ argument associates the 
’DPSContextRec’ data structure with a system-specific imaging 
object — in this case, an X drawable object, which could be a 
window or a pixmap. ‘DPSTextProc’ and ‘DPSErrorProc’ are 
standard procedures types declared in dpsclient.h; their type 
definitions are included here for ease of reading. 

‘space’ identifies the private PostScript VM in which the new 
context executes. If ‘space’ is ‘NULL’, a new space is created for 
the context; otherwise, it will share the specified space with con- 
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texts previously created in the space. A simple application that 
creates one space and one context can pass ‘NULL’ for the 
‘space’ argument. See the PostScript Language Reference 
Manual for a definition of VM. See Section 4.6 for more infor¬ 
mation about spaces. 

‘textProc’ and ‘errorProc’ point to customizable facilities for 
handling text and errors sent by the interpreter. Passing ‘NULL’ 
for these arguments is allowed but means that text and errors are 
ignored. For simple applications, it is sufficient to specify the 
system-specific default text procedure ( DPSDefaultTextBackstop 
in the X Window System implementation) and 
DPSDefaultErrorProc. Use DPSGetCurrentTextBacIcstop to get 
the current default text procedure. See Section 5 for more infor¬ 
mation on text handlers and error handlers. 

XDPSCreateSimpleContext creates a context for which the 
PostScript interpreter is the destination of code and data sent to 
the context. It is sometimes useful to send the code and data 
elsewhere, such as to a file, to a terminal (UNIX® stdout ), or to a 
printer; see DPSCreateTextContext. 


DPSContext DPSCreateTextContext(textProc, errorProc) 
DPSTextProc textProc; 

DPSErrorProc errorProc; 


DPSCreateTextContext creates a context whose input is con¬ 
verted to ASCII encoding (text that is easily transmitted and 
easily read by humans); see Section 6.2. The ASCII-encoded text 
is passed to the ‘textProc’ procedure rather than to the PostScript 
interpreter. Since the application provides the implementation of 
the ‘textProc’ procedure, it determines where the ASCII text 
goes from there. The text can be sent to a file, to a terminal, or 
perhaps to a printer’s communication port. 

The ‘errorProc’ associated with a context handles errors that 
arise when a wrap or Client Library procedure is called with that 
context. The ‘textProc’ should call the ‘errorProc’ to handle an 
error only when an appropriate error code is defined. See the 
discussion of text and error handlers in Section 5. 
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4.4 THE CURRENT CONTEXT 

The current context is the one that was specified by the last call 
to DPSSetContext. If the application has only one context, 
DPSSetContext may be called once when the application is 
initialized. If the application manages more than one context, it 
must explicitly set the current context when necessary. 

Many Client Library procedures do not require the application to 
specify a context; they assume the current context. This is true of 
all of the single-operator procedures defined in the psops.h 
header file as well as any wrapped procedures that were defined 
to use the current context implicitly. 

An application can find out which is the current context by call¬ 
ing DPSGetCurrentContext. 

4.5 SENDING CODE AND DATA TO A CONTEXT 

Once the context has been created, the application can send 
PostScript language code to it by calling procedures such as: 

• Wraps (custom wrapped procedures developed for the 
application). 

• Single-operator procedures defined in dpsops.h and 
psops.h. 

• DPSPrintf, DPSWritePostScript, and DPSWriteData — 
Client Library procedures provided for writing to a context. 

A wrapped procedure is a PostScript language program encoded 
as a binary object sequence; binary object sequences are 
described in Section 11.4 and in PostScript Language Extensions 
for the Display PostScript System. The creation of wrapped 
procedures is discussed in the pswrap Reference Manual. Once 
the PostScript language program has been embedded in the body 
of a wrap by using the pswrap translator, it can be called like any 
other C procedure. 

Example 1: Consider a wrap that draws a small colored circle 
around the point where the mouse was clicked, given an RGB 
color and the x,y coordinate returned by a mouse-click event. 
The exact PostScript language implementation is left as an ex- 
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ercise for the reader, but the C declaration of the wrap might 
look like this: 

extern void PSWDrawSmallCircle(/* 

DPSContext ctxt; int x, y; float r, g, b 7); 

An application might call this procedure as part of the code that 
handles mouse clicks. Suppose the struct ‘event’ contains the x,y 
coordinate. To draw a bright green circle around the spot, call 
the wrapped procedure with the following arguments: 

PSWDrawSmallCircle(ctxt, event.x, event.y, 0.0,1.0,0.0); 

Example 2: If a wrap returns values, the procedure that calls it 
must pass pointers to the variables into which the values will be 
stored. Consider a wrap that, given a font name, tells whether the 
font is in the SharedFontDirectory. Define the wrap like this: 

defineps PSWFontLoaded( 

DPSContext ctxt; char *fontName I boolean ’found) 

The corresponding C declaration is: 

extern void PSWFontLoaded(/* 

DPSContext ctxt; char 'fontName; int ’found 7); 

Note that booleans are of C type ‘int’. Call the wrapped proce¬ 
dure by providing a pointer to a variable of type ‘int’: 

int fontFound; 

PSWFontLoaded(ctxt, "Courier", &fontFound); 

Wraps are the most efficient way to specify any PostScript lan¬ 
guage program as a C-callable procedure. 

Example 3: Occasionally, a very small PostScript language 
program — on the order of one operator — is needed. This is a 
case where a single-operator procedure is appropriate. For ex¬ 
ample, to get the current gray level, simply provide a pointer to a 
float and call the single-operator procedure equivalent of the 
PostScript currentgray operator: 
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float gray; 

DPScurrentgray(ctxt, &gray); 


See Section 10.3 for a complete listing of single-operator proce¬ 
dure declarations. 

Example 4: DPSPrintf is one of the Client Library facilities 
provided for writing PostScript language code directly to a con¬ 
text. 

DPSPrintf is similar to the Standard C Library routine printf. It 
formats arguments into ASCII text and writes this text to the 
context. Small PostScript language programs or text data may be 
sent in this way. Here is an example that sends formatted text to 
the show operator to represent an author’s byline: 

struct { 

int x, y; /* location on page for byline 7 

char ‘titleString; /* title of document 7 
char ‘authorsName; /* name of author 7 
} byline; 

DPSPrintf(ctxt, "%d %d moveto (%s by %s) show\n", 
byline.x, 
byline.y, 

byline.titleString, 

byline.authorsName); 

The x,y coordinate is formatted in place of the two ‘%d’ field 
specifiers, the title replaces the first ‘%s\ followed by “by” fol¬ 
lowed by the author’s name in place of the second ‘%s’. 
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Warning: When using DPSPrintf, it’s important to leave some 
whitespace (newline with ‘\n\ or just a space) at the very end of 
the format string if the string ends with an operator. PostScript 
language code written to a context appears as a continuous 
stream. Thus, consecutive calls to DPSPrintf will appear as if all 
the text were sent at once. For example, suppose the following 
calls were made: 

DPSPrintf(ctxt, "gsave"); 

DPSPrintf(ctxt, ’stroke*); 

DPSPrintf(ctxt, "grestore"); 

The context will receive a single string ‘gsavestrokegrestore’, 
with all the operators run together. Of course, this effect may be 
useful for constructing a long string that isn’t a part of a 
program. But when sending operators to be executed, don’t for¬ 
get to put whitespace at the end of each format string; for ex¬ 
ample: 

DPSPrintf(ctxt, "gsave\n"); 


Example 5: The DPSWritePostScript procedure is a facility 
provided for writing PostScript language code of any encoding 
to a context. If DPSChangeEncoding is provided by the system- 
specific interface, DPSWritePostScript can be used to convert a 
binary-encoded PostScript language program into another binary 
form (for instance, binary object sequences to binary-encoded 
tokens) or into ASCII text. Code destined for immediate execu¬ 
tion by the interpreter should be sent as binary object sequences. 
Code that’s intended to be read by a human should be sent as 
ASCII text. See Section 6.2 for a discussion of language encod¬ 
ings. 
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Warning: Although PostScript language of any encoding may 
be written to a context, unexpected results can occur when inter¬ 
mixing code of different encodings. This is particularly impor¬ 
tant when ASCII encoding is mixed with binary encoding. (See 
PostScript Language Extensions for the Display PostScript 
System for a discussion of encodings.) 

The following code, which looks correct, may fail with a syntax 
error in the interpreter, depending on the contents of the buffer: 

while (/* more buffers to send 7) { 
count = GetBuffer(file, buffer); 

DPSWritePostScript(ctxt, buffer, count); 

MyWrap(ctxt); 

} 

GetBuffer reads a PostScript language program in the ASCII en¬ 
coding from a file. The call to MyWrap generates a binary ob¬ 
ject sequence. If the program in the buffer passed to 
DPSWritePostScript is complete, with no partial tokens, 
MyWrap works correctly. Imagine, however, that the end of the 
buffer contains a partial token, ‘mov\ and the next buffer starts 
with ‘eto’. In this instance, the binary object sequence represent¬ 
ing MyWrap will be inserted immediately after the partial token, 
resulting in a syntax error. 

This warning applies to all procedures that send code or data to a 
context, including the Client Library procedures DPSPrintf, 
DPSWritePostScript, DPSWriteData, and DPSWaitContext. 


Example 6: To send any type of data to a context (such as 
hexadecimal image data), or to avoid the automatic conversion 
behavior built into DPSWritePostScript, use DPSWriteData. See 
Section 9.2 for details on DPSWritePostScript and 
DPSWriteData. 

The following example reads hexadecimal image data line by 
line from a file and sends the data to a context: 
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while (ifeof(fp)) { 

fgets(buf, BUFSIZE, fp); 

DPSWriteData(ctxt, buf, strlen(buf)); 

} 

4.6 SPACES 

A context is created in a space. The space is either shared with a 
previously created context or is created when a new context is 
created. Multiple contexts in the same space share all data; care¬ 
ful coordination is required to ensure that they don’t interfere 
with each other. Contexts in different spaces can operate more or 
less independently and still share data by using shared VM. See 
the discussion of VM and spaces in the PostScript Language 
Reference Manual. 

Destroying a space automatically destroys all of the contexts 
within it. DPSDestroySpace calls DPSDestroyContext for each 
context in the space. 

The parameters that define a space are contained in a record of 
type ‘DPSSpaceRec’. 

4.7 INTERRUPTS 

An application may need to interrupt a PostScript language 
program running in the PostScript interpreter. Call 
DPSInterruptContext for this purpose. (Note that although this 
procedure returns immediately, an indeterminate amount of time 
may pass before execution is actually interrupted.) 

An interrupt request causes the context to execute an interrupt 
error. Since the implementation of the interrupt error can be 
changed by the application, the exact results of requesting an 
interrupt cannot be defined here. The default behavior is that the 
stop operator will execute. For a discussion of the interrupt er¬ 
ror, see the PostScript Language Reference Manual', for a discus¬ 
sion of error handling in the Client Library, see Section 5.4. 
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4.8 DESTROYING CONTEXTS 

An application should destroy all the contexts it creates by call¬ 
ing DPSDestroyContext or DPSDestroySpace when they are no 
longer needed. Destroying a context does not destroy the space it 
occupies, but destroying a space destroys all of its contexts; see 
Section 4.6. 

If an application terminates abnormally, the PostScript inter¬ 
preter detects that the application has terminated and destroys 
any spaces and contexts that the application had created. 
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5 HANDLING OUTPUT FROM THE CONTEXT 


Output is information returned from the PostScript interpreter to 
the application. In the Display PostScript system, three kinds of 
output are possible: 

• Output parameters (results) from wrapped procedures. 

• ASCII text written by the context (for example, by the 
print operator). 

• Errors. 

Each kind of output is handled by a separate mechanism in the 
Client Library. The handling of results is discussed in Section 
11. The handling of text and errors is discussed in the remainder 
of this section. 


Note: You may not get text and error output when you expect 
it. 

For example, a wrap that generates text to be sent back to the 
application (for instance, with the print operator) may return be¬ 
fore the application actually receives the text. Unless the appli¬ 
cation and the interpreter are synchronized (see Section 6.4), the 
text may not appear until some other Client Library procedure or 
wrap is called. This is due to delays in the communication chan¬ 
nel or delays in scheduling execution of the context in the 
PostScript interpreter. 

These kinds of delays are a particularly important consideration 
for handling errors, since the notification of the error may be 
received by the application long after the code that caused the 
error was sent. 

Keep these issues in mind while reading the remainder of Sec¬ 
tion 5. 


5.1 CALL-BACK PROCEDURES 

The application programmer must specify call-back procedures 
to handle text and errors. A call-back procedure is code provided 
by an application and called by a system function. 
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A text handler is a call-back procedure that handles text output 
from the context. It is specified in the ‘textProc’ field of the 
‘DPSContextRec’. A system-specific default text handler may be 
provided; in the Display PostScript system extension for the X 
Window System, the default text handler is 
DPSDefaultTextBackstop. 

An error handler is a call-back procedure that handles errors 
arising when the context is passed as a parameter to any Client 
Library procedure or wrap. It is specified in the ‘errorProc’ field 
of the ‘DPSContextRec’. DPSDefaultErrorProc is the default er¬ 
ror handler provided with every Client Library implementation. 

Text and error handlers are associated with a given context when 
the context is created, but the DPSSetTextProc and 
DPSSetErrorProc procedures, described in Section 9.2, give the 
application the flexibility to change these handlers at any time. 

Using a call-back procedure reverses the normal flow of control, 
which is as follows: 

• An application that is active calls the system to provide ser¬ 
vices; for example, to get memory or open a file. 

• The application then gives up control until the system has 
provided the service. 

• The system procedure returns control to the application, 
passing it the result of the service that was requested. 

In the case of call-back procedures, the application wants a cus¬ 
tom service provided at a time when it is not in control. It does 
this as follows: 

• The application notifies the system, often but not neces¬ 
sarily at initialization time, of the address of the call-back 
procedure to be invoked when the system recognizes a cer¬ 
tain condition, say, an error condition. 

• When the error is raised, the system gets control. 

• The system passes control to the error handler specified by 
the application — thus “calling back” the application. 

• The error handler does processing on behalf of the appli¬ 
cation. 
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• When the error handler completes, it returns not to the ap¬ 
plication but to the system. 

In the Display PostScript system, the text and error handlers in 
the Client Library interface are designed to be used this way. 


Note: Client Library procedures and wraps should not be called 
from within a call-back procedure. This restriction protects the 
application against unintended recursion. 


5.2 TEXT HANDLERS 

A context generates text output with operators such as print, 
writestring, and =. The application handles this text output 
with a text handler, which is specified in the ‘textProc’ field of 
the ‘DPSContextRec’. The text handler is passed a buffer of text 
and a count of the number of characters in the buffer; what is 
done with this buffer is up to the application. The text handler 
may be called several times to handle large amounts of text. Note 
that the Client Library just gets buffers; it doesn’t provide any 
logical structure for the text and it doesn’t indicate (or know) 
where the text ends. 

The text handler may be called as a side effect of calling a wrap, 
a single-operator procedure, or a Client Library procedure that 
takes a context. You can’t predict when the text handler for a 
context will be called unless the application is synchronized (see 
Section 6.4). 

5.3 EXAMPLE TEXT HANDLER 

Consider an application that normally displays a log window to 
which it appends plain text or error messages received from the 
interpreter. The handlers for this window were associated with 
the context when it was created. Occasionally, the application 
calls a wrapped procedure that generates a block of text intended 
for a file. Before calling the text-generating procedure, the appli¬ 
cation must install a temporary text handler for its output. The 
temporary text handler stores the text it receives in a file instead 
of in the log window. When the text-generating procedure com¬ 
pletes, the application restores the original text handler. 
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An example of such an application, written for the X Window 
System, is shown below. 


/* EXAMPLE TEXT HANDLER FOR AN X WINDOW SYSTEM APPLICATION 7 

/* wrapped procedure that generates text 7 

defineps WrapThatGeneratesText(DPSContext ctxt I boolean *done) 

% send a text representation of the contents of mydict 
mydict {== ==} forall 

% returning a value flushes output as a side-effect 
true done 
endps 

/* normal text proc appends to a log window 7 

void LogTextProc(ctxt, buf, count) 

DPSContext ctxt; 
char *buf; 

long unsigned int count; 

{ 

/*... code that appends text to a log window... 7 

} 

/* special text proc stores text to a file 7 

void StoreTextProc(ctxt, buf, count) 

DPSContext ctxt; 
char *buf; 

long unsigned int count; 

{ 

/*... code that appends text to a file... 7 

} 

/* application initialization 7 

ctxt = XDPSCreateSimpleContext(dpy, drawable, gc, x, y, 

LogTextProc, DPSDefaultErrorProc, NULL); 

/* main loop for application 7 

while (XPending(dpy)) > 0 { 

/* get an input event 7 
XNextEvent(dpy, &event); 

I* react to event 7 
switch (event.type) { 

r any text that comes from processing EVENT_A or EVENT_B is logged 7 
case EVENT_A:... 
case EVENT.B:... 

/* but EVENT.C means store the text in a file 7 
case EVENT.C: { 
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int done; 

DPSTextProc tmp = ctxt -> textProc; 

/* make sure interpreter is ready 7 
DPSWaitContext(ctxt); 

/* temporarily install the other text proc 7 
DPSSetTextProc(ctxt, StoreTextProc); 

/* call the wrapped procedure 7 
WrapThatGeneratesText(ctxt, &done); 

/* since wrap returned a value, we know the interpreter is 
ready when we get here; restore original textProc 7 
DPSSetTextProc(ctxt, tmp); 

/* close file by calling textProc with count = 07 

StoreTextProc(ctxt, NULL, 0); 

break; 

} 

/* ... 7 
default:; 

} 

} 


5.4 ERROR HANDLERS 

The ‘errorProc’ field in the ‘DPSContextRec’ contains the ad¬ 
dress of a call-back procedure for handling errors. The error call¬ 
back procedure is called when there is a PostScript language er¬ 
ror or when an error internal to the Client Library, such as use of 
an invalid context identifier, is encountered. The standard error 
codes are listed under DPSErrorProc in Section 9.2. 

When the interpreter detects a PostScript language error, it in¬ 
vokes the standard handleerror procedure to report the error, 
then forces the context to terminate. The error call-back proce¬ 
dure specified in the ‘DPSContextRec’ is called with the 
‘dps_err_ps’ error code. 

After a PostScript language error, the context becomes invalid; 
further use of it will cause another error. See Section 5.5 for a 
discussion of error recovery issues. See Appendix B for an ex¬ 
ample of an error handler. See the Note on page 21 for a discus¬ 
sion of when error output is actually received. 
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5.5 ERROR RECOVERY REQUIREMENTS 

For many applications, error recovery may not be considered an 
issue because an unanticipated PostScript language error or 
Client Library error represents a bug in the program that will be 
fixed during development. However, since applications do some¬ 
times go into production with undiscovered bugs, it is prudent to 
provide an error handler that allows the application to exit grace¬ 
fully. 

There are a small number of applications that require error 
recovery more sophisticated than simply exiting. If an applica¬ 
tion falls into one of the following categories, it is likely that 
some form of error recovery will be needed: 

• Applications that read and execute PostScript language 
programs generated by other sources (for example, a 
previewer application for PostScript language documents 
generated by a word-processing program). Since the exter¬ 
nally provided PostScript language program may have er¬ 
rors, the application must provide some sort of error 
recovery. 

• Applications that allow the user to enter PostScript lan¬ 
guage programs. This category is a subset of the one 
above. 

• Applications that generate PostScript language programs 
dynamically in response to user requests (for example, a 
graphics art program that generates an arbitrarily long path 
description of a graphical object). Since there are system- 
specific resource limitations on the interpreter, such as 
memory and disk space, the application should be able to 
back away from an error caused by exhausting a resource, 
and perhaps attempt to acquire new or reclaim used 
resources. 

Error recovery is complicated because both the Client Library 
and the context can be left in unknown states. For example, the 
operand stack may have unused objects on it. 

In general, if an application needs to intercept and recover from 
PostScript language errors, keep it simple. For some applica¬ 
tions, the best strategy when an error occurs is either to destroy 
the space and construct a new one with a new context or to res¬ 
tart the application. 
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A given implementation of the Client Library may provide more 
sophisticated error recovery facilities; consult your system- 
specific documentation. Your system may provide the general- 
purpose exception-handling facilities described in Appendix C, 
which can be used in conjunction with DPSDefaultErrorProc. 

5.6 BACKSTOP HANDLERS 

Backstop handlers handle output when there is no other ap¬ 
propriate handler. The Client Library automatically installs back¬ 
stop handlers. 

To get a pointer to the current backstop text handler, call 
DPSGetCurrentTextBackstop. To install a new backstop text 
handler, call DPSSetTextBackstop. The text backstop may be 
used as a default text handler implementation. The exact defini¬ 
tion of what the default text handler does is system specific. For 
instance, for UNIX systems, it writes the text to stdout. 

To get a pointer to the current backstop error handler, call 
DPSGetCurrentErrorBackstop. To install a new backstop error 
handler, call DPSSetErrorBackstop. The backstop error handler 
processes errors internal to the Client Library, such as a lost 
server connection. These errors have no specific ‘DPSContext’ 
handle associated with them and therefore have no error handler. 
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6 ADDITIONAL CLIENT LIBRARY FACILITIES 

The Client Library includes a number of utilities and support 
functions for applications. This section describes: 

• Sending the same code and data to a group of contexts by 
chaining them. 

• Encoding and translating PostScript language code. 

• Buffering and flushing the buffer. 

• Synchronizing an application with a context. 

• Communicating with a forked context. 

6.1 CHAINED CONTEXTS 

It is sometimes useful to send the same PostScript language 
program to several contexts. This is accomplished most con¬ 
veniently by chaining the contexts together and sending input to 
one context in the chain; for example, by calling a wrap with that 
context. 

Two Client Library procedures are provided for managing con¬ 
text chaining: 

• DPSChainContext links a context to a chain. 

• DPSUnchainContext removes a child context from its 
parent’s chain. 

One context in the chain is specified as the parent context, the 
other as the child context. The child context is added to the 
parent’s chain. Subsequently, any input sent to the parent is sent 
to its child, and the child of the child, and so on. Input sent to a 
child is not passed to its parent. A context can appear on only 
one chain. If the context is already a child on a chain, 
DPSChainContext returns a nonzero error code. However, you 
can chain a child to a context that already has a child. 
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Note: A parent context always passes its input to its child con¬ 
text. However, for a chain of more than two contexts, the order 
in which the contexts on the chain receive the input is not 
defined. Therefore an application should not rely on 
DPSChainContext to create a chain whose contexts process input 
in a particular order. 


For chained contexts, output is handled differently from input, 
and text and errors are handled differently from results. If a con¬ 
text on a chain generates text or error output, the output is 
handled by that context only. Such output is not passed to its 
child. When a wrap that returns results is called, all of the con¬ 
texts on the chain get the wrap code (the input), but only the 
context with which the wrap was called receives the results. 

The best way to build a chain is to identify one context as the 
parent. Call DPSChainContext to make each additional context 
the child of that parent. For example, to chain contexts A, B, C, 
and D, choose A as the parent and make the following calls to 
DPSChainContext: 

DPSChainContext(A, B); 

DPSChainContext(A,C); 

DPSChainContext(A, D); 

Once the chain is built, send input only to the designated parent, 
A. 

The most common use of chained contexts is in debugging. A 
log of PostScript operators executed may be kept by a child con¬ 
text whose purpose is to convert PostScript language programs 
to ASCII text and write the text to a file; this child is chained to a 
parent context that sends normal application requests to the inter¬ 
preter. The parent’s calls to wrapped procedures will then be 
logged in human-readable form as a debugging audit trail. 

Chained contexts may also be used for duplicate displays. An 
application may want several windows, or even several different 
display screens, to show the same graphics without having to 
explicitly call the wrapped procedure in a loop for all of the con¬ 
texts. 
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6.2 ENCODING AND TRANSLATION 

PostScript language code may be sent to a context in three ways: 

• As a binary object sequence — typically for immediate 
execution on behalf of a context. 

• As binary-encoded tokens — typically for deferred execu¬ 
tion from a file. 

• As ASCII text — typically for debugging, display, or 
deferred execution from a file. 

PostScript Language Extensions for the Display PostScript 
System describes the encodings available in the PostScript lan¬ 
guage. 

Since the application and the PostScript interpreter can be on 
different machines, the Client Library automatically ensures that 
the binary representation of numeric values, including byte order 
and floating-point format, are correctly interpreted. 

6.2.1 Encoding PostScript Language Code 

On a system-specific basis, the Client Library supports a variety 
of conversions to and from the encodings and formats defined 
for the PostScript language: 

• Binary object sequence to binary object sequence. For ex¬ 
panding user name indices back to their printable names. 

• Binary object sequence to ASCII encoding. For backward 
compatibility with printers, for interchange, and for debug¬ 
ging- 

• Binary object sequence to binary-encoded tokens. For 
long-term storage. 

• Binary-encoded tokens to ASCII. For backward com¬ 
patibility and interchange. 

‘DPSProgramEncoding’ defines the three encodings available to 
PostScript language programs. ‘DPSNameEncoding’ defines the 
two possible encodings for user names in PostScript language 
programs. See Section 11.6 for the type definitions. 

6.2.2 Translation 
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Translation means the conversion of program encoding or name 
encoding from one form to another. 

Any code sent to the context is converted according to the setting 
of the encoding fields. For a context that was created with the 
system-specific routine DPSCreateTextContext, code is 
automatically converted to ASCII encoding. 

An application sometimes exchanges binary object sequences 
with another application. Since binary object sequences have 
user name indices by default, the sending application must 
provide name-mapping information to the receiving application; 
this information can be lengthy. Instead, some implementations 
allow the application to translate name indices back into user 
names by changing the ‘nameEncoding’ field to ‘dps_strings’. In 
many implementations, DPSChangeEncoding performs this 
function. 

6.3 BUFFERING 

For optimal performance, programs and data sent to a context 
may be buffered by the Client Library. For the most part, the 
application programmer need not be concerned with this buffer¬ 
ing. Flushing of the buffer happens automatically as required, 
such as just before waiting for input events. 

However, in certain unusual situations, the application may ex¬ 
plicitly flush a buffer (see example below). DPSFlushContext al¬ 
lows the application to force any buffered code or data to be sent 
to the context. Note that flushing does not guarantee that code is 
executed by the context, only that any buffered code is sent to 
the context. See Section 6.4 and DPSWaitContext for informa¬ 
tion on how to force code to be executed. 

Unnecessary flushing is inefficient. It is unusual for the appli¬ 
cation to flush the buffer explicitly. Cases where the buffer 
might need to be flushed include the following: 

• Nothing to send to the interpreter for a long time (for ex¬ 
ample, “going to sleep” or doing a long computation). 

• Nothing expected from the interpreter for a long time. 
(Note that getting input automatically flushes the output 
buffers.) 
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When the client and the server are separate processes and the 
buffered code need not be executed immediately, the application 
can flush the buffers with flush rather than synchronizing with 
the context; synchronizing is described in Section 6.4. 

6.4 SYNCHRONIZING APPLICATION AND CONTEXT 

The PostScript interpreter can run as a separate operating-system 
process (or task) from the application; it can even run on a 
separate machine. When the processes are separate, an applica¬ 
tion programmer must take into account the communication be¬ 
tween the application and the PostScript interpreter. This is im¬ 
portant when time-critical actions must be performed based on 
the current appearance of the display. Also, errors arising from 
the execution of a wrapped procedure may be reported long after 
the procedure returns. 

The application and the context are synchronized when all code 
sent to the context has been executed and it is waiting to execute 
more code. When the two are not synchronized, the status of 
code previously sent to the context is unknown to the applica¬ 
tion. Synchronization can be effected in two ways: as a side ef¬ 
fect of calling wraps that return values, or explicitly, by calling 
the DPSWaitContext procedure. 

A wrapped procedure that has no result values returns as soon as 
the wrap body is sent to the context. The data buffer is not neces¬ 
sarily flushed in this case. Sometimes, however, the application’s 
next action depends on the completed execution of the wrap 
body by the PostScript interpreter. The following example 
describes the kind of problem that can occur when the assump¬ 
tion is made that a wrap’s code has been executed by the time it 
returns: 

Example: An application calls a wrapped procedure to draw a 
large and complex picture into an offscreen buffer (such as an 
XI1 pixmap). The wrapped procedure has no return value, so it 
returns immediately, although the context may not have finished 
executing the code. At this point, the application calls procedures 
to copy the screen buffer to a window for display. If the context 
has not finished drawing the picture into the buffer, only part of 
the image will be displayed on the screen. This is not what the 
application programmer had in mind. 
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Wrapped procedures that return results flush any code waiting to 
be sent to the context and then wait until all results have been 
received. Therefore they automatically synchronize the context 
with the application. The wrapped procedure will not return until 
the interpreter indicates that all results have been sent. 2 In this 
case, the application knows that the context is ready to execute 
more code as soon as the wrapped procedure returns. 

The preceding discussion describes the side effect of calling a 
wrap that returns a value, but it is not always convenient, or 
indeed correct, to write wrapped procedures that return values. 
Forcing the application to wait for a return result for every wrap 
is inefficient and may degrade performance. 

If an application has a few critical points where synchronization 
must occur, and a wrap that returns results is not needed, 
DPSWaitContext may be used to synchronize the application 
with the context. DPSWaitContext flushes any buffered code, 
and then waits until the context finishes executing all code that 
has been sent to it so far. This forces the context to finish before 
the application continues. 

Like wraps that return results, DPSWaitContext should be used 
only when necessary. Performance may be degraded by exces¬ 
sive synchronization. 

6.5 FORKED CONTEXTS 

When the fork operator is executed in the PostScript interpreter, 
a new execution context is created, but the application has no 
way to communicate with it. In order to communicate with a 
forked context, it must create a ‘DPSContextRec’ for it. For ex¬ 
ample, DPSContextFromContextID is an X Window System pro¬ 
cedure that creates a ‘DPSContextRec’ for a forked context. 


2 But the wrapped procedure may return prematurely if an error occurs, depend¬ 
ing on how the error handler works; see Section 5.4. 
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DPSContext DPSContextFromContextlD(ctxt, cid, textProc, errorProc) 
DPSContext ctxt; 
long int cid, 

DPSTextProc textProc, 

DPSErrorProc errorProc; 


‘ctxt’ is the context that executed the fork operator. 

‘cid’ is the integer value of the new context’s identifier. ‘NULL’ 
is returned if ‘cid’ is invalid. 

If ‘textProc’ or ‘errorProc’ are ‘NULL’, 
DPSContextFromContextID copies the corresponding procedure 
pointer from ‘ctxt’ to the new ‘DPSContext’; otherwise the new 
context gets the specified ‘textProc’ and ‘errorProc’. 

All other fields of the new context are initialized with values 
from ‘ctxt’, including the space field. 
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7 PROGRAMMING TIPS 


This section contains tips for avoiding mistakes commonly made 
by programmers using the Client Library interface. Some of the 
items listed here are brief summaries of Notes and Warnings 
emphasized elsewhere in this document. Section 7.1 contains 
some pointers on how to make the best use of the PostScript 
language imaging model. 

• Don’t guess what the arguments to a single-operator proce¬ 
dure call are — look them up in the listing. See Section 
10 . 

• Make sure that variables passed to wrapped procedures and 
single-operator procedures are of the correct C type. A 
common mistake is to pass a pointer to a ‘short int’ (only 
16 bits wide) to a procedure that returns a boolean. A 
boolean is defined as an ‘int’, which can be 32 bits wide on 
some systems. 

• Make sure that PostScript language code is properly 
separated by whitespace when using DPSPrintf. Make sure 
that variables passed to DPSPrintf are of the right type. 
Passing type ‘float’ to a format string of ‘%d’ will yield 
unpredictable results. See Section 4.5. 

• There are two means of synchronizing the application with 
the context: either call DPSWaitContext, which causes the 
application to wait until the interpreter has executed all the 
code sent to the execution context, or call a wrap that 
returns a result, which causes synchronization as a side ef¬ 
fect. If synchronization is not required, use a wrap that 
returns results only when results are needed. Unnecessary 
synchronization by either method will degrade perfor¬ 
mance. See Section 6.4. 

• Use of DPSFlushContext is usually not necessary. See 
Section 6.3. 

• Do not read from the file returned by the operator 
currentfile from within a wrap. In general, do not read 
directly from the context’s standard input stream %stdin 
from within a wrap. Since a binary object sequence is a 
single token, the behavior of the code is different from 
what it would be in another encoding, such as ASCII. This 
will lead to unpredictable results. See the pswrap Refer- 
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ence Manual and PostScript Language Extensions for the 
Display PostScript System. 

• If the context is an execution context for a display, do not 
write PostScript language programs, particularly in wraps, 
that depend on reading the end-of-file (EOF) indicator. 
Support for EOF on the communication channel is system 
specific, and should not be relied upon. However, 
PostScript language programs that will be written to a file 
or spooled to a printer can make use of EOF indications. 

• Be careful when sending intermixed encoding types to a 
context. In particular, it’s best to avoid mixing ASCII en¬ 
coding with binary encoding. See the warning on page 18 
for an example; see also the following tip on 
DPSWaitContext. 

• Before calling DPSWaitContext, make sure that code that 
has already been sent to the context is syntactically com¬ 
plete, such as a wrap or a correctly terminated PostScript 
operator or composite object. 

• Use of the fork operator requires understanding of a given 
system’s support for handling errors from the forked con¬ 
text. A common error while developing multiple context 
applications is to fail to handle errors arising from forked 
contexts. See Section 5.4. 

• To avoid unintended recursion, do not call Client Library 
procedures or wraps from within a call-back procedure. 

• To avoid confusion about which context on a chain will 
handle output, don’t send input to a context that’s been 
made the child of another context; send input only to the 
parent. (This doesn’t apply to text contexts, since they 
never get output.) 

• Program wraps carefully. Copying the entire prologue 
from a PostScript printer driver into a wrap without change 
is probably not going to result in efficient code. 

• Avoid the temptation to do all of your programming in the 
PostScript language. Because the PostScript language is 
interpreted, not compiled, the application can generally do 
arithmetic computation and data manipulation such as sort¬ 
ing more efficiently in C. Reserve the PostScript language 
for what it does best — displaying text and graphics. 
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7.1 USING THE IMAGING MODEL 


The device-independent and resolution-independent imaging 
model defined by the PostScript language is described in the 
PostScript Language Reference Manual. For general advice on 
how to use the PostScript language efficiently and detailed ad¬ 
vice on how to write page descriptions, see PostScript Language 
Program Design. Although that book is primarily concerned 
with printer applications, much of its information on the imaging 
model can be applied to writing applications for the Display 
PostScript system. A thorough understanding of the imaging 
model is essential to writing efficient Display PostScript system 
applications. 

The imaging model helps make your application device and 
resolution independent. Device independence ensures that your 
application will work and look as you intended on any display or 
print media. Resolution independence lets you use the power of 
the PostScript language to do scaling, rotation, and transfor¬ 
mation of your graphical display without loss of quality. Use of 
the imaging model will automatically give you the best possible 
rendering for any device. 

Design your application with the imaging model in mind. Con¬ 
sider issues like converting coordinate systems, representing 
paths and graphics states with data structures, rendering colors 
and patterns, setting text, and accessing fonts (to name just a 
few). 

A few specific tips are listed below: 

• Coordinates sent to the PostScript interpreter should be in 
the user coordinate system (user space). Although it may 
be more convenient to express coordinates in the window 
coordinate system, this makes your code resolution depend¬ 
ent. Your application will run more efficiently if you com¬ 
pute the coordinate conversions to and from user space in C 
code, rather than letting the interpreter do it. 

• Think in terms of color. Avoid programming to the lowest 
common denominator (low-resolution monochrome). The 
imaging model will always give the best rendering possible 
for a device, so use colors even if you expect that your 
application may be run on monochrome or gray-scale 
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devices. Avoid using setgray unless you really want black, 
white, or a gray level. Use setrgbcolor for all other cases. 
The imaging model will use a gray level or halftone pattern 
if the device does not support color, so objects of different 
colors will be distinguishable from one another. 

• Don’t use setlinewidth with a width of zero to get thin 
lines. On high-resolution devices, the lines will be prac¬ 
tically invisible. To get lines narrower than one point, use 
fractions of 1 such as 0.3 or 0.25. 
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8 EXAMPLE APPLICATION PROGRAM 

This section provides a simple example of how to use the Dis¬ 
play PostScript system through the Client Library. The example: 

• Establishes communication with an XI1 server. 

• Creates a window and a context. 

• Draws an ochre rectangle in the window. 

• Waits for a mouse-button click. 

• Terminates when the button is pressed. 

To use the PostScript imaging model, an application must 
describe its graphical operations in the PostScript language. 
Therefore an application using the Display PostScript system is a 
combination of C code and PostScript language code. 

The pswrap program generates a C code file and a C header file 
that defines the interface to the procedures in the code file. The 
application source code and the pswrap output file are compiled 
and linked together with the program libraries of the Client 
Library to form the executable application program. Figure 2 il¬ 
lustrates the complete process. 
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Figure 2 Creating an Application 



8.1 EXAMPLE C CODE 

The following code is used in conjunction with the wrap in the 
next section. See the description that follows. 


r 

example.c - simple X Window System application. Uses Display Postscript 
to draw an ochre box and uses X primitives to wait for a mouse click before 
terminating. 

7 


#include <stdio.h> 
#include <string.h> 
#include <X11/X.h> 
#include <X11/Xlib.h> 
#include <X11/lntrinsic.h> 
#include "psops.h" 


r Standard C library I/O routines 7 
I* Standard C library string routines 7 
/* X definitions 7 
/* Interface to X library 7 
i* X toolkit definitions 7 
/* Interface to PostScript single-op wraps 7 
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#include “dpsXclient.h" /* Interface to the DPS Client Library 7 
#include "examplewraps.h" /* Interface to user-defined “wrap" procedures 7 

/* Window geometry definitions 7 
#define XWINDOW_X_ORIGIN 100 

#define XWINDOW_Y_ORIGIN 100 

#define XWINDOW_WIDTH 500 

#define XWINDOW_HEIGHT 500 

void main(argc, argv) 
int argc; 
char *argv[]; 

{ 

Display *dpy; /* X display structure 7 

int screen; /* screen on display 7 

DPSContext ctxt; /* DPS drawing context 7 

DPSContext txtCtxt; /* DPS text context for debugging 7 

Window xWindow; /* window where drawing occurs 7 

int blackPixel, whitePixel; 

int debug = {FALSE }; 

GC gc; 

XSetWindowAttributes attributes; 
unsigned long mask; 

DPSSpace space; 
float x, y, width, height; 

/* Connect to the window server by opening the display. Most of command 
line is parsed by XtOpenDisplay, leaving any options not recognized by 
the X toolkit: look for local -debug switch 7 

XtToolkitlnitialize(); 

dpy = XtOpenDisplay(NULL, (String) NULL, "example", "example", 
(XrmOptionDescRec *) NULL, 0, &argc, argv); 
screen = DefaultScreen(dpy); 
if (argc == 2) 

if (strcmp(argv[1], "-debug") == 0) 
debug = TRUE; 
else{ 

printf("Usage: example [-display xx:0] [-sync] [-debug]\n"); 
exit(1); 

} 

I* Create a window to draw in: register interest in mouse button events. 7 

blackPixel = BlackPixel (dpy, screen); 

whitePixel = WhitePixel (dpy, screen); 

attributes.background_pixel = whitePixel; 

attributes.border_pixel = blackPixel; 

attributes.bit_gravity = SouthWestGravity; 

attributes.event_mask = ButtonPressMask I ButtonReleaseMask; 

mask = CWBackPixel I CWBorderPixel I CWBitGravity I CWEventMask; 
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xWindow = XCreateWindow(dpy, DefaultRootWindow(dpy), 

XWINDOW_X_ORIGIN, XWINDOW_Y_ORIGIN, XWINDOW_WIDTH, XWINDOW.HEIGHT, 
1, CopyFromParent, InputOutput, CopyFromParent, mask, &attributes); 

XMapWindow(dpy, xWindow); 

gc = XCreateGC(dpy, RootWindow(dpy, screen), 0, NULL); 

XSetForeground(dpy, gc, blackPixel); 

XSetBackground(dpy, gc, whitePixel); 

/* Create a DPS context to draw in the window we just created. If the 
user has asked for debugging, create a text context chained to the 
’drawing’ context. 7 

ctxt = XDPSCreateSimpleContext(dpy, xWindow, gc, 0, XWINDOW_HEIGHT, 
DPSDefauitTextBackstop, DPSDefaultErrorProc, NULL); 
if (ctxt == NULL) { 

fprintf(stderr, "Error attempting to create DPS context\n“); 
exit(1); 

} 

DPSSetContext(ctxt); 
if (debug) { 

txtCtxt = DPSCreateTextContext(DPSDefaultTextBackstop, DPSDefaultErrorProc); 
DPSChainContext(ctxt, txtCtxt); 

} 

I* Convert the X Window System coordinates at the lower right corner 
of the window to get the width and height in user space. 7 

PSitransform( 

(float) XWIN DOW_WI DTH, 

(float) -XWINDOWJHEIGHT, 

&width, 

&height); 

/* Locate the box in the middle of the window. 7 

x = width / 4.0; 
y = height / 4.0; 

/* Paint an ochre box. 7 

PSWDrawBox(0.77, 0.58, 0.02, x, y, width / 2.0, height / 2.0); 

/* Wait for a mouse click on any button then terminate 7 

while (NextEvent() != ButtonPress); 
while (NextEvent() != ButtonRelease); 

space = DPSSpaceFromContext(ctxt); 

DPSDestroySpace(space); 

exit(0); 
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} /* main 7 

int NextEvent() 

{ 

XEvent event; 

XtNextEvent(&event); 

return(event.type); 

} 


8.2 EXAMPLE WRAP 

This wrap provides the PostScript language routine used by the 
example application. It is shown as examplewraps.psw in Figure 
2 on page 40. 


r wrap for example application 7 

defineps PSWDrawBox(float r, g, b, x, y, width, height) 
gsave 

r g b setrgbcolor 
x y width height rectfill 
grestore 
endps 


8.3 DESCRIPTION OF THE EXAMPLE APPLICATION 

The example application demonstrates the use of Client Library 
functions and custom wraps in the XI1 environment. The appli¬ 
cation is simple: it draws a rectangle in the middle of a window, 
waits for a mouse button click in the window, and terminates. 

The program starts by initializing the toolkit and connecting to 
the display device. Command-line options can include all op¬ 
tions recognized by the X Intrinsics resource manager plus a lo¬ 
cal ‘-debug’ option, which demonstrates the use of a chained 
text context for debugging. 

The program creates a window that will contain the drawing 
produced by the PostScript operators. The window’s attributes 
are set to indicate interest in mouse button events in that win¬ 
dow. 
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The program creates a context with ‘xWindow’ as its ‘drawable’. 
The system-specific default handlers DPSDefaultTextBackstop 
and DPSDefaultErrorProc are specified in the 
XDPSCreateSimpleContext call. These handlers are adequate for 
this application. 

If the ‘-debug’ option was selected, the program creates a con¬ 
text that converts binary-encoded PostScript language programs 
into readable text. The text is passed to ‘PrintProc’. This context 
is then chained to the drawing context. The result is that any 
code sent to the drawing context will be also sent to the text 
context and displayed on stdout. This is a common technique for 
debugging wrapped procedures. 

Now that the application is completely initialized, PostScript lan¬ 
guage code can be executed to draw a rectangle into the window. 
This is done by using both a single-operator procedure and a 
customized wrapped procedure. 

The single-operator procedure PSitransform determines the 
bounds of the window in terms of PostScript user space; this 
allows the program to scale the size of the rectangle ap¬ 
propriately. 

The wrap procedure PSWDrawBox takes red, green, and blue 
levels to specify the color of the rectangle. It also takes x,y coor¬ 
dinates for the bottom left comer of the rectangle, and it takes 
the rectangle’s width and height. Simple arithmetic computation 
is most efficiently done in C code by the application, rather than 
in PostScript language code by the interpreter. 

PSWDrawBox is called to draw a colored square. If the display 
supports color, you’ll see a square painted in ochre (a dark shade 
of orange). The values 0.77 for red, 0.58 for green, and 0.02 for 
blue approximate the color ochre. If the display supports only 
gray scale or monochrome, you’ll see a square painted in some 
shade of gray. 

The program now waits for events. Since the only events regis¬ 
tered in this window are mouse-button events, events such as 
window movement and resizing are not directed to the appli¬ 
cation. When a button-press event is followed by a button- 
release event, the program destroys the space used by the draw- 
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ing context. This destroys the context and its chained text con¬ 
text as well. The program then terminates normally. 
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9 THE DPSCUENT.H HEADER FILE 


DPSContext 


This section documents the dpsclient.h procedures that constitute 
the core of the Client Library. They are system independent. 

9.1 DPSCLIENT.H DATA STRUCTURES 

This section documents: 

• The standard context record. 

• The standard error codes. 

The context record, ‘DPSContextRec’, is shared by the appli¬ 
cation and the PostScript interpreter. Except for its ‘priv’ field, 
this data structure should not be altered directly. The dpsclient.h 
header file provides procedures to alter it. 

When calling Client Library procedures, refer to the context 
record by its handle, ‘DPSContext’. 


/* handle for context record 7 
See ‘DPSContextRec’. 
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DPSContextRec 


typedef struct _t_DPSContextRec { 
char *priv; 

DPSSpace space; 

DPSProgramEncoding programEncoding; 
DPSNameEncoding nameEncoding; 

DPSProcs procs; 
void (*textProc)(); 
void (*errorProc)(); 

DPSResults resuItTable; 

unsigned int resuItTableLength; 

struct _t_DPSContextRec *chainParent, *chainChild; 

} DPSContextRec, *DPSContext; 

defines the data structure pointed to by ‘DPSContext’. 


Note: This record is used by dpsclient.h procedures but is ac¬ 
tually defined in the dpsfriends.h header file. 


‘priv’ is provided for use by application code. It is initialized to 
‘NULL’ and is not touched thereafter by the Client Library im¬ 
plementation. 


Warning: Although it is possible to read all the fields of the 
‘DPSContextRec’ record directly, they should not be modified 
directly except for ‘priv’. Data structures internal to the Client 
Library depend on the values in these fields and must be notified 
when they change. Call the procedures provided for this pur¬ 
pose, such as DPSSetTextProc. 


‘space’ identifies the space in which the context executes. 

‘programEncoding’ and ‘nameEncoding’ describe the encoding 
of the PostScript language that is sent to the interpreter. The 
values in these fields are established when the context is created. 
Whether or not the encoding fields can be changed after creation 
is system specific. 

‘procs’ points to a ‘struct’ containing procedures that implement 
the basic context operations, including writing, flushing, inter¬ 
rupting, and so on. 

The Client Library implementation calls the ‘textProc’ and 
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‘errorProc’ procedures to handle interpreter-generated ASCII 
text and errors. 

‘resuItTableLength’ and ‘resuItTable’ define the number, type, 
and location of results expected by a wrap. They are set up by 
the wrap procedure before any values are returned; see 
DPSSetResultTable in Section 11.7. 

‘chainParent’ and ‘chainChild’ are used for chaining contexts. 
‘chainChild’ is a pointer to the context that automatically 
receives code and data sent to the context represented by this 
‘DPSContextRec’. ‘chainParent’ is a pointer to the context that 
automatically sends code and data to the context represented by 
this ‘DPSContextRec’. See the discussion of chained contexts in 
Section 6.1 for more information. 


DPSErrorCode typedef int DPSErrorCode; 

defines the type of error code used by the Client Library. Here 
are the standard error codes: 

• ‘dps_err_ps’ identifies standard PostScript interpreter er¬ 
rors. 

• l dps_err_nameTooLong’ flags user names that are too 
long. 128 characters is the maximum length for PostScript 
language names. 

• ‘dps_err_resultTagCheck’ flags erroneous result tags, most 
likely due to erroneous explicit use of the printobject 
operator. 

• ‘dps_err_resultTypeCheck’ flags incompatible result types. 

• ‘dps_err_invalidContext’ flags an invalid ‘DPSContext’ ar¬ 
gument. An attempt to send PostScript language code to a 
context that has terminated is the most likely cause of this 
error. 

For more information, see DPSErrorProc in Section 9.2. 


9.2 DPSCLIENT.H PROCEDURES 

This section contains descriptions of the procedures in the Client 
Library header file dpsclient.h, listed alphabetically. 
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DPSChainContext int DPSChainContext(parent, child); 

DPSContext parent, child; 

links ‘child’ onto the context chain of ‘parent’. This is the chain 
of contexts that automatically receive a copy of any code or data 
sent to ‘parent’. A context appears on only one such chain. 

DPSChainContext returns zero if it successfully chains ‘child’ to 
‘parent’. It fails if ‘child’ is on another context’s chain; in that 
case it returns -1. 

See Section 6.1 for more information. 


DPSDefaultErrorProc 

void DPSDefaultErrorProc(ctxt, errorCode, argl, arg2); 

DPSContext ctxt; 

DPSErrorCode errorCode; 
long unsigned int argl, arg2; 

is a sample DPSErrorProc for handling errors from the 
PostScript interpreter. See Appendix B for a listing of the code 
and a description of the procedure. 

The meaning of ‘argl’ and ‘arg2’ depend on ‘errorCode’. See 
DPSErrorProc. 


DPSDestroyContext 

void DPSDestroyContext(ctxt) 

DPSContext ctxt; 

destroys the context represented by ‘ctxt’. The context is first 
unchained if it is on a chain. 

What happens to buffered input and output when a context is 
destroyed is system specific; in the X Window System it is dis¬ 
carded. 

Destroying a context does not destroy its space; see 
DPSDestroySpace. 
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DPSDestroySpace 

void DPSDestroySpace(spc) 

DPSSpace spc; 

destroys the space represented by ‘spc’. This is necessary for 
application termination and clean-up. It also destroys all contexts 
within ‘spc’. 
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DPSErrorProc 


typedef void (*DPSErrorProc)(/* 

DPSContext ctxt; 

DPSErrorCode errorCode; 
long unsigned int argl, arg2;*/); 

handles errors caused by the context. These can be PostScript 
language errors reported by the interpreter or errors that occur 
when the Client Library is called with a context. ‘errorCode’ is 
one of the predefined codes that specify the type of error encoun¬ 
tered; see ‘DPSErrorCode’ in Section 9.1 for its type definition. 
‘errorCode’ determines the interpretation of ‘argl’ and ‘arg2’. 

The following list shows how ‘argl’ and ‘arg2’ are handled for 
each ‘errorCode’: 

‘dps_err_ps’ PostScript language error, ‘argl’ is the address 
of the binary object sequence sent by the 
handleerror operator to report the error. The se¬ 
quence has one object, which is an array of four 
objects. ‘arg2’ is the number of bytes in the en¬ 
tire binary object sequence. 

‘dps_err_nameTooLong’ 

Error in wrap argument. The PostScript user 
name and its length are passed as ‘argl’ and 
‘arg2’. A name of more than 128 characters 
causes an error. 

‘dps_err_resultT agCheck’ 

Error in formulation of wrap. The pointer to the 
binary object sequence and its length are passed 
as ‘argl’ and ‘arg2’. There is one object in the 
sequence. 

‘dps_err_resultTypeCheck’ 

Incompatible result types. A pointer to the bi¬ 
nary object is passed as ‘argl’; ‘arg2’ is unused. 

‘dps_err_invalidContext’ 

Stale context handle (probably terminated), 
‘argl ’ is a context identifier; ‘arg2’ is unused. 
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DPSFlushContext void DPSFIushContext(ctxt) 

DPSContext ctxt; 

forces any buffered code or data to be sent to ‘ctxt’. Some Client 
Library implementations use buffering to optimize performance. 

DPSGetCurrentContext 

DPSContext DPSGetCurrentContext(); 

returns the current context. 


DPSGetCurrentErrorBackstop 

DPSErrorProc DPSGetCurrentErrorBackstopO; 

returns the ‘errorProc’ passed most recently to 

DPSSetErrorBackstop, or ‘NULL’ if none was set. 

DPSGetCurrentTextBackstop 

DPSTextProc DPSGetCurrentTextBackstopO; 

returns the ‘textProc’ passed most recently to 

DPSSetTextBackstop, or ‘NULL’ if none was set. 


DPSInterruptContext 

void DPSInterruptContext(ctxt) 

DPSContext ctxt; 

notifies the interpreter to interrupt the execution of the context, 
resulting in the PostScript language interrupt error. The proce¬ 
dure returns immediately after sending the notification. 


DPSPrintf void DPSPrintf(ctxt, fmt, [, arg ...]); 

DPSContext ctxt; 
char *fmt; 

sends string ‘fmt’ to ‘ctxt’ with the optional arguments converted, 
formatted, and logically inserted into the string in a manner iden¬ 
tical to the Standard C Library routine print/. It is useful for 
sending formatted data or a short PostScript language program to 
a context. 
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DPSResetContext void DPSResetContext(ctxt) 
DPSContext ctxt; 


resets the context after an error occurs. It ensures that any buf¬ 
fered I/O is discarded and that the context is ready to read and 
execute more input. DPSResetContext works in conjunction with 

resynchandleerror. 


DPSSetContext void DPSSetContext(ctxt) 

DPSContext ctxt; 

sets the current context. Call DPSSetContext before calling any 
procedures defined in psops.h. 


DPSSetErrorBackstop 

void DPSSetErrorBackstop(errorProc) 

DPSErrorProc errorProc; 

establishes ‘errorProc’ as a pointer to the backstop error handler. 
This error handler handles errors that are not handled by any 
other error handler. ‘NULL’ will be passed as the ‘ctxt’ argument 
to the backstop error handler. 


DPSSetErrorProc void DPSSetErrorProc(ctxt, errorProc) 
DPSContext ctxt; 

DPSErrorProc errorProc; 

changes the context’s error handler. 


DPSSetTextBackstop 

void DPSSetTextBackstop(textProc) 

DPSTextProc textProc; 

establishes the procedure pointed to by ‘textProc’ as the handler 
for text output for which there is no other handler. The text hand¬ 
ler acts as a backstop for text output. 


DPSSetTextProc void DPSSetTextProc(ctxt, textProc) 
DPSContext ctxt; 

DPSTextProc textProc; 

changes the context’s text handler. 
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DPSSpaceFromContext 

DPSSpace DPSSpaceFromContext(ctxt) 

DPSContext ctxt; 

returns the space handle for the specified context. It returns 
‘NULL’ if ‘ctxt’ does not represent a valid execution context. 


DPSTextProc typedef void (*DPSTextProc)(/* 

DPSContext ctxt; 
char *buf; 

long unsigned int count; 7); 

handles text emitted from the interpreter — for example, by the 
== operator, ‘buf’ is a pointer to ‘count’ characters. 


DPSUnchainContext 

void DPSUnchainContext(ctxt) 

DPSContext ctxt; 

removes ‘ctxt’ from the chain that it is on, if any. The parent and 
child pointers of the unchained context are set to ‘NULL’. 


DPSWaitContext void DPSWaitContext(ctxt) 

DPSContext ctxt; 

flushes output buffers belonging to ‘ctxt’ and then waits until the 
interpreter is ready for more input to ‘ctxt’. It is not necessary to 
call DPSWaitContext after calling a wrapped procedure that 
returns a value. 

Before calling DPSWaitContext, you must ensure that the last 
code sent to the context is syntactically complete, such as a wrap 
or a correctly terminated PostScript operator or composite ob¬ 
ject. 
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DPSWriteData 


void DPSWriteData(ctxt, buf, count) 

DPSContext ctxt; 
char *buf; 
unsigned int count; 

sends ‘count’ bytes of data from ‘buf’ to ‘ctxt’. ‘ctxt’ specifies 
the destination context, ‘buf’ points to a buffer that contains 
‘count’ bytes of data. The contents of the buffer will not be con¬ 
verted according to the context’s encoding parameters. 


DPSWritePostScript 

void DPSWritePostScript(ctxt, buf, count); 

DPSContext ctxt; 
char *buf; 
unsigned int count; 

sends PostScript language to a context in any of the three lan¬ 
guage encodings, ‘ctxt’ specifies the destination context, ‘buf’ 
points to a buffer that contains ‘count’ bytes of PostScript lan¬ 
guage code. The code in the buffer will be converted according 
to the context’s encoding parameters as needed; refer to the 
system-specific documentation for a list of supported conver¬ 
sions. 
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10 SINGLE-OPERATOR PROCEDURES 


For each operator defined in the PostScript language, the Client 
Library provides a procedure to invoke the most common usage 
of the operator. These are called the single-operator procedures. 
(See the PostScript Language Reference Manual and PostScript 
Language Extensions for the Display PostScript System for com¬ 
plete information about how these PostScript operators work.) If 
the predefined usage is not the one you need, it’s easy to write 
wraps for variant forms of the operators. 

There are two Client Library header files for single-operator 
procedures: dpsops.h and psops.h. The name of the Client 
Library single-operator procedure is the name of the PostScript 
operator preceded by either DPS or PS 3 : 

DPS prefix Used when the context is explicitly specified; for 
example, DPSgsave. The first argument must be 
of type ‘DPSContext’. These single-operator 
procedures are defined in dpsops.h. 

PS prefix Used when the context is assumed to be the cur¬ 
rent context; for example, PSgsave. These 
single-operator procedures are defined in 
psops.h. The procedure DPSSetContext, defined 
in dpsclient.h, sets the current context. 

For example, to execute the PostScript operator translate, the 
application can call 

DPStranslate(ctxt, 1.23,43.56) 

where ‘ctxt’ is a variable of type ‘DPSContext’, the handle that 
represents a PostScript execution context. 

The DPStranslate procedure sends the binary encoding of 

1.23 43.56 translate 

to execute in ‘ctxt’. 


3 Most PostScript operator names are lowercase, but some contain uppercase 
letters; for example FontDirectory. In either case, the name of the correspond¬ 
ing single-operator procedure is formed simply by prefixing PS or DPS. 
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10.1 SETTING THE CURRENT CONTEXT 


The single-operator procedures in psops.h assume the current 
context. The DPSSetContext procedure, defined in dpsclient.h, 
sets the current context. When the application deals with only 
one context it is convenient to use the procedures in psops.h 
rather than those in dpsops.h. In this case, the application would 
set the current context during its initialization phase: 

DPSSetContext(ctxt); 

In subsequent calls on the procedures in psops.h, ‘ctxt’ is used 
implicitly. For example: 

PStranslate(1.23,43.56); 

has the same effect as 

DPStranslate(ctxt, 1.23, 43.56); 

The explicit method is preferable for situations that require inter¬ 
mingling of calls to multiple contexts. 


Note: It is important to pass the correct C types to the single¬ 
operator procedures. (See Section 10.3 for the procedure 
declarations.) In general, if a PostScript operator takes operands 
of arbitrary numeric type, the corresponding single-operator pro¬ 
cedure takes parameters of type ‘float’. Coordinates are always 
type ‘float’. Passing an integer literal to a procedure that expects 
a floating-point literal is a common error: 

incorrect: PSIineto(72,72); 

correct: PSIineto(72.0, 72.0); 


Procedures that appear to have no input arguments may actually 
take their operands from the operand stack — for example, 
PSdef and DPSdef. 

10.2 TYPES IN SINGLE-OPERATOR PROCEDURES 

When using single-operator procedures, be sure to inspect the 
calling protocol (that is, order and types of formal parameters) 
for every procedure to be called; these are listed in Section 10.3. 
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Note: Throughout Section 10.2, references to single-operator 
procedures with a DPS prefix are equally applicable to the equiv¬ 
alent procedures with a PS prefix. 


10.2.1 Rules of Thumb 

There is no completely consistent system for associating data 
types with particular single-operator procedures. In general, it’s 
safest to look up the definition in Section 10.3 or in the header 
file. However, there are a few rules of thumb that can be applied. 
Note that all of these rules have exceptions. 

• Coordinates are specified as type ‘float’. For example, all 
of the standard path construction operators (moveto, lineto, 
curveto, and so on), take type ‘float’. 

• Booleans are always type ‘int’. The comment 7* int *b */’ 
or 7* int *it */’ in the header file means that the procedure 
returns a boolean. 

• If the operator takes either integer or floating-point num¬ 
bers, the corresponding procedure takes type ‘float’. If the 
operator specifies a number type (such as rand and 
vmreclaim), then the procedure takes arguments of that 
type (typically type ‘int’). 

• Operators that return values must always be specified with 
a pointer to the appropriate data type. For example, 
currentgray returns the current gray value of the graphics 
state. You must pass DPScurrentgray a pointer to a vari¬ 
able of type ‘float’. 

• If an operator takes a data type that does not have a directly 
analogous C type, such as dictionaries, graphic states, and 
executable arrays, the single-operator procedure takes no 
arguments. It is assumed that the programmer will arrange 
for the appropriate data to be on the operand stack before 
calling the procedure; see DPSsendchararray and 
DPSsendfloat, among others. 

• If a single-operator procedure takes or returns a matrix, the 
matrix is specified as ‘float m[]’, which is an array of six 
floating-point numbers. 

• In general, the integer parameter ‘size’ is used to specify 
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the length of a variable-length array; see, for example, 
DPSxshow. For single-operator procedures that take two 
variable-length arrays as parameters, the length of the first 
array is specified by the integer ‘n’; the length of the 
second array is specified by the integer ‘I’; see, for ex¬ 
ample, DPSustroke. 

The following operators are worth noting for unusual order and 
types of arguments, or for other irregularities. After reading 
these descriptions, inspect the declarations in the listing in this 
document or in the header file: 

• DPSdefmeuserobject takes no arguments. One would ex¬ 
pect it to take at least the index argument, but because of 
the requirement to have the arbitrary object on the top of 
the stack, it is probably better to send the index down 
separately, perhaps via DPSsendint. 

• DPSgetchararray, DPSgetfloatarray, and other “get 
array” operators specify the length of the array first, fol¬ 
lowed by the array. (Mnemonic: Get the array last.) 

• DPSsendchararray, DPSsenclfloatarray, and other ‘ ‘send 
array” operators specify the array first, followed by the 
length of the array. (Mnemonic: Send the array first.) 

• DPSinfdl, DPSinstroke, and DPSinufill support only the 
x,y-coordinate version of the operator. The optional second 
userpath argument is not supported. 

• DPSinueofdl, DPSinufill, DPSinustroke, DPSuappend, 
DPSueofill, DPSufill, DPSustroke, and DPSustrokepath 
take a userpath in the form of an encoded number string 
and operator string. Note that the lengths of the strings 
follow the strings themselves, as arguments. See 
PostScript Language Extensions for the Display PostScript 
System for details. 

• DPSsetdash takes an array of numbers of type ‘float’ for the 
dash pattern. 

• DPSselectfont takes type ‘float’ for the font scale 
parameter. 

• DPSsetgray takes type ‘float’. (‘DPSsetgray(l)’ is wrong.) 

• DPSxshow, DPSxyshow, DPSyshow take an array of num¬ 
bers of type ‘float’ for specifying the coordinates of each 
character. 
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• DPSequals is the procedure equivalent to the = operator. 

• DPSequalsequals is the procedure equivalent to the == 
operator. 

• DPSversion returns the version number in a character array 
*buf[]’ whose length is specified by ‘bufsize’. 

10.2.2 Special Cases 

A few of the single-operator procedures have been optimized to 
take user objects for arguments, since they are most commonly 
used in this way. In the listing in Section 10.3, these user object 
arguments are specified as type ‘int’, which is the correct type of 
a user object. 

• DPScurrentgstate takes a user object that represents the 
gstate object into which the current graphics state should be 
stored. The gstate object is left on the stack. 

• DPSsetfont takes a user object that represents the font dic¬ 
tionary. 

• DPSsetgstate takes a user object that represents the gstate 
object that the current graphics state should be set to. 
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10.3 DPSOPS.H PROCEDURE DECLARATIONS 


The procedures in dpsops.h and psops.h are identical except for 
the first argument, dpsops.h procedures require the ‘ctxt’ argu¬ 
ment; psops.h procedures do not. The procedure name is the 
lowercase PostScript operator name preceded by “DPS” or 
“PS” as appropriate. For the sake of brevity, only the dpsops.h 
procedures are listed here. 


Note: DPSSetContext must have been called before calling any 
procedure in psops.h. 


extern void DPSFontDirectory( /* DPSContext ctxt; 7); 

extern void DPSISOLatin1Encoding( /* DPSContext ctxt; 7); 

extern void DPSSharedFontDirectory( /* DPSContext ctxt; 7); 

extern void DPSStandardEncoding( /* DPSContext ctxt; 7); 

extern void DPSUserObjects( /* DPSContext ctxt; 7); 

extern void DPSabs( /* DPSContext ctxt; 7); 

extern void DPSadd( /* DPSContext ctxt; 7); 

extern void DPSaload( /* DPSContext ctxt; 7); 

extern void DPSanchorsearch( /* DPSContext ctxt; int 'truth; 7); 

extern void DPSand( /* DPSContext ctxt; 7); 

extern void DPSarc( /* DPSContext ctxt; float x, y, r, anglel, angle2; 7); 
extern void DPSarcn( /* DPSContext ctxt; float x, y, r, anglel, angle2; 7); 
extern void DPSarct( /* DPSContext ctxt; float xl, yl, x2, y2, r; 7); 

extern void DPSarcto(/' DPSContext ctxt; float xl, yl, x2, y2, r; float 'xtl, 'ytl, *xt2, *yt2; 7); 

extern void DPSarray( /* DPSContext ctxt; int len; 7); 

extern void DPSashow( /* DPSContext ctxt; float x, y; char *s; 7); 

extern void DPSastore( /* DPSContext ctxt; 7); 

extern void DPSatan( /* DPSContext ctxt; 7); 

extern void DPSawidthshow( /* DPSContext ctxt; float cx, cy; int c; float ax, ay; char's; 7); 
extern void DPSbanddevice( /* DPSContext ctxt; 7); 
extern void DPSbegin( /* DPSContext ctxt; 7); 
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extern void DPSbind( /* DPSContext ctxt; 7); 

extern void DPSbitshift( /* DPSContext ctxt; int shift; 7); 

extern void DPSbytesavailable( /* DPSContext ctxt; int *n; 7); 

extern void DPScachestatus( /* DPSContext ctxt; */); 

extern void DPSceiling( /* DPSContext ctxt; 7); 

extern void DPScharpath( /* DPSContext ctxt; char *s; int b; */); 

extern void DPSclear( /* DPSContext ctxt; 7); 

extern void DPScleardictstack( /* DPSContext ctxt; */); 

extern void DPScleartomark( /* DPSContext ctxt; */); 

extern void DPSclip( /* DPSContext ctxt; 7); 

extern void DPSclippath( /* DPSContext ctxt; 7); 

extern void DPSclosefile( /* DPSContext ctxt; 7); 

extern void DPSclosepath( /* DPSContext ctxt; 7); 

extern void DPSco!orimage( /* DPSContext ctxt; 7); 

extern void DPSconcat( /* DPSContext ctxt; float m[]; 7); 

extern void DPSconcatmatrix( /* DPSContext ctxt; 7); 

extern void DPScondition( /* DPSContext ctxt; 7); 

extern void DPScopy( /* DPSContext ctxt; int n; 7); 

extern void DPScopypage( /* DPSContext ctxt; 7); 

extern void DPScos( /* DPSContext ctxt; 7); 

extern void DPScount( /* DPSContext ctxt; int *n; 7); 

extern void DPScountdictstack( /* DPSContext ctxt; int *n; 7); 

extern void DPScountexecstack( /* DPSContext ctxt; int *n; 7); 

extern void DPScounttomark( /* DPSContext ctxt; int *n; 7); 

extern void DPScurrentblackgeneration( /* DPSContext ctxt; 7); 

extern void DPScurrentcacheparams( /* DPSContext ctxt; 7); 

extern void DPScurrentcmykcolor( /* DPSContext ctxt; float *c, *m, *y, *k; 7); 

extern void DPScurrentcolorscreen( I* DPSContext ctxt; 7); 

extern void DPScurrentcolortransfer( /* DPSContext ctxt; 7); 

extern void DPScurrentcontext( /* DPSContext ctxt; int *cid; 7); 
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extern void DPScurrentdash( /* DPSContext ctxt; 7); 

extern void DPScurrentdict( /* DPSContext ctxt; 7); 

extern void DPScurrentfile( /* DPSContext ctxt; 7); 

extern void DPScurrentflat( /* DPSContext ctxt; float 'flatness; 7); 

extern void DPScurrentfont( /* DPSContext ctxt; 7); 

extern void DPScurrentgray( /* DPSContext ctxt; float 'gray; 7); 

extern void DPScurrentgstate( /* DPSContext ctxt; int gst; 7); 

extern void DPScurrenthalftonef f* DPSContext ctxt; 7); 

extern void DPScurrenthalftonephase( /* DPSContext ctxt; float 'x, *y; 7); 

extern void DPScurrenthsbcolor( /* DPSContext ctxt; float *h, *s, *b; 7); 

extern void DPScurrentlinecap( /* DPSContext ctxt; int 'linecap; 7); 

extern void DPScurrentlinejoin( /* DPSContext ctxt; int 'linejoin; 7); 

extern void DPScurrentlinewidth( /* DPSContext ctxt; float 'width; 7); 

extern void DPScurrentmatrix( /* DPSContext ctxt; 7); 

extern void DPScurrentmiterlimit( /* DPSContext ctxt; float 'limit; 7); 

extern void DPScurrentobjectformat( /* DPSContext ctxt; int 'code; 7); 

extern void DPScurrentpacking( /* DPSContext ctxt; int *b; 7); 

extern void DPScurrentpoint( /* DPSContext ctxt; float *x, *y; 7); 

extern void DPScurrentrgbcolor( /* DPSContext ctxt; float *r, *g, *b; 7); 

extern void DPScurrentscreen( /* DPSContext ctxt; 7); 

extern void DPScurrentshared( /* DPSContext ctxt; int *b; 7); 

extern void DPScurrentstrokeadjust( /* DPSContext ctxt; int *b; 7); 

extern void DPScurrenttransfer( /* DPSContext ctxt; 7); 

extern void DPScurrentundercolorremoval(/* DPSContext ctxt; 7); 

extern void DPScurveto( /* DPSContext ctxt; float xl, yl, x2, y2, x3, y3; 7); 

extern void DPScvi( /* DPSContext ctxt; 7); 

extern void DPScvlit( /* DPSContext ctxt; 7); 

extern void DPScvn( /* DPSContext ctxt; 7); 

extern void DPScvr( /* DPSContext ctxt; 7); 

extern void DPScvrs( /* DPSContext ctxt; 7); 
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extern void DPScvs( /* DPSContext ctxt; 7); 
extern void DPScvx( /* DPSContext ctxt; 7); 
extern void DPSdef( /* DPSContext ctxt; 7); 
extern void DPSdefaultmatrix( /* DPSContext ctxt; 7); 
extern void DPSdefinefont( /* DPSContext ctxt; 7); 

extern void DPSdefineusername( /* DPSContext ctxt; int i; char ‘username; 7); 

extern void DPSdefineuserobject( /* DPSContext ctxt; 7); 

extern void DPSdeletefile( /* DPSContext ctxt; char ‘filename; 7); 

extern void DPSdetach( /* DPSContext ctxt; 7); 

extern void DPSdeviceinfo( /* DPSContext ctxt; 7); 

extern void DPSdict( /* DPSContext ctxt; int len; 7); 

extern void DPSdictstack( /* DPSContext ctxt; 7); 

extern void DPSdiv( /* DPSContext ctxt; 7); 

extern void DPSdtransform( /* DPSContext ctxt; float xl, yl; float *x2, *y2; 7); 

extern void DPSdup( /* DPSContext ctxt; 7); 

extern void DPSecho( /* DPSContext ctxt; int b; 7); 

extern void DPSend( /* DPSContext ctxt; 7); 

extern void DPSeoclip( /* DPSContext ctxt; 7); 

extern void DPSeofill( /* DPSContext ctxt; 7); 

extern void DPSeoviewclip( /* DPSContext ctxt; 7); 

extern void DPSeq( /* DPSContext ctxt; 7); 

extern void DPSequals( /* DPSContext ctxt; 7); 

extern void DPSequalsequals(/* DPSContext ctxt; 7); 

extern void DPSerasepage( /* DPSContext ctxt; 7); 

extern void DPSerrordict( /* DPSContext ctxt; 7); 

extern void DPSexch( /* DPSContext ctxt; 7); 

extern void DPSexec( /* DPSContext ctxt; 7); 

extern void DPSexecstack( /* DPSContext ctxt; 7); 

extern void DPSexecuserobject( /* DPSContext ctxt; int userObjlndex; 7); 

extern void DPSexecuteonly( /* DPSContext ctxt; 7); 
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extern void DPSexit( /* DPSContext ctxt; 7); 

extern void DPSexp( /* DPSContext ctxt; V); 

extern void DPSfalse( /* DPSContext ctxt; 7); 

extern void DPSfile( /* DPSContext ctxt; char *name, ‘access; 7); 

extern void DPSfilenameforall( /* DPSContext ctxt; 7); 

extern void DPSfileposition( /* DPSContext ctxt; int *pos; 7); 

extern void DPSfill( /* DPSContext ctxt; 7); 

extern void DPSfindfont( /* DPSContext ctxt; char ‘name; 7); 

extern void DPSflattenpath( /* DPSContext ctxt; 7); 

extern void DPSfloor( /* DPSContext ctxt; 7); 

extern void DPSflush( /* DPSContext ctxt; 7); 

extern void DPSflushfile( /* DPSContext ctxt; 7); 

extern void DPSfor( /* DPSContext ctxt; 7); 

extern void DPSforall( /* DPSContext ctxt; 7); 

extern void DPSfork( /* DPSContext ctxt; 7); 

extern void DPSframedevice( /* DPSContext ctxt; 7); 

extern void DPSge( /* DPSContext ctxt; 7); 

extern void DPSget( /* DPSContext ctxt; 7); 

extern void DPSgetboolean( /* DPSContext ctxt; int ‘it; 7); 

extern void DPSgetchararray( /* DPSContext ctxt; int size; char s[]; 7); 

extern void DPSgetfloat( /* DPSContext ctxt; float ‘it; 7); 

extern void DPSgetfloatarray( /* DPSContext ctxt; int size; float a[]; 7); 

extern void DPSgetint( /* DPSContext ctxt; int ‘it; 7); 

extern void DPSgetintarray( /* DPSContext ctxt; int size; int a[]; 7); 

extern void DPSgetinterval( /* DPSContext ctxt; 7); 

extern void DPSgetstring( /* DPSContext ctxt; char *s; 7); 

extern void DPSgrestore( /* DPSContext ctxt; 7); 

extern void DPSgrestoreall( /* DPSContext ctxt; 7); 

extern void DPSgsave( /* DPSContext ctxt; 7); 

extern void DPSgstate( /* DPSContext ctxt; 7); 
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extern void DPSgt( /* DPSContext ctxt; 7); 
extern void DPSidentmatrix( /* DPSContext ctxt; 7); 
extern void DPSidiv( /* DPSContext ctxt; 7); 

extern void DPSidtransform( /* DPSContext ctxt; float xl, yl; float *x2, *y2; 7); 

extern void DPSif( I* DPSContext ctxt; 7); 

extern void DPSifelse( /* DPSContext ctxt; 7); 

extern void DPSimage( /* DPSContext ctxt; 7); 

extern void DPSimagemask( /* DPSContext ctxt; 7); 

extern void DPSindex( /* DPSContext ctxt; int i; 7); 

extern void DPSineofill( /* DPSContext ctxt; float x, y; int *b; 7); 

extern void DPSinfill( /* DPSContext ctxt; float x, y; int *b; 7); 

extern void DPSinitclip( /* DPSContext ctxt; 7); 

extern void DPSinitgraphics( /* DPSContext ctxt; 7); 

extern void DPSinitmatrix( /* DPSContext ctxt; 7); 

extern void DPSinitviewclip( /* DPSContext ctxt; 7); 

extern void DPSinstroke( /* DPSContext ctxt; float x, y; int *b; 7); 

extern void DPSinueofill( /* DPSContext ctxt; float x, y; char nums[]; int n; char ops[]; int I; int *b; 7); 

extern void DPSinufill( /* DPSContext ctxt; float x, y; char nums[]; int n; char ops[]; int I; int *b; 7); 

extern void DPSinustroke( /* DPSContext ctxt; float x, y; char nums[]; int n; char ops[]; int I; int *b; 7); 

extern void DPSinvertmatrix( /* DPSContext ctxt; 7); 

extern void DPSitransform( /* DPSContext ctxt; float xl, yl; float *x2, *y2; 7); 

extern void DPSjoin( /* DPSContext ctxt; 7); 

extern void DPSknown( /* DPSContext ctxt; int *b; 7); 

extern void DPSkshow( /* DPSContext ctxt; char *s; 7); 

extern void DPSIe( I* DPSContext ctxt; 7); 

extern void DPSIength( /* DPSContext ctxt; int *len; 7); 

extern void DPSIineto( /* DPSContext ctxt; float x, y; 7); 

extern void DPSIn( /* DPSContext ctxt; 7); 

extern void DPSIoad( /* DPSContext ctxt; 7); 

extern void DPSIock( /* DPSContext ctxt; 7); 
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extern void DPSIog( /* DPSContext ctxt; 7); 

extern void DPSIoop( /* DPSContext ctxt; 7); 

extern void DPSIt( /* DPSContext ctxt; 7); 

extern void DPSmakefont( /* DPSContext ctxt; 7); 

extern void DPSmark( /* DPSContext ctxt; 7); 

extern void DPSmatrix( /* DPSContext ctxt; 7); 

extern void DPSmaxlength( /* DPSContext ctxt; int *len; 7); 

extern void DPSmod( /* DPSContext ctxt; 7); 

extern void DPSmonitor( /* DPSContext ctxt; 7); 

extern void DPSmoveto( /* DPSContext ctxt; float x, y; 7); 

extern void DPSmul( /* DPSContext ctxt; 7); 

extern void DPSne( /* DPSContext ctxt; 7); 

extern void DPSneg( /* DPSContext ctxt; 7); 

extern void DPSnewpath( /* DPSContext ctxt; 7); 

extern void DPSnoaccess( /* DPSContext ctxt; 7); 

extern void DPSnot( /* DPSContext ctxt; 7); 

extern void DPSnotify( /* DPSContext ctxt; 7); 

extern void DPSnull( /* DPSContext ctxt; 7); 

extern void DPSnulldevice( /* DPSContext ctxt; 7); 

extern void DPSor( /* DPSContext ctxt; 7); 

extern void DPSpackedarray( /* DPSContext ctxt; 7); 

extern void DPSpathbbox( /* DPSContext ctxt; float *llx, *lly, *urx, *ury; 7); 

extern void DPSpathforall( /* DPSContext ctxt; 7); 

extern void DPSpop( /* DPSContext ctxt; 7); 

extern void DPSprint( /* DPSContext ctxt; 7); 

extern void DPSprintobject( /* DPSContext ctxt; int tag; 7); 

extern void DPSprompt( /* DPSContext ctxt; 7); 

extern void DPSpstack( /* DPSContext ctxt; 7); 

extern void DPSput( /* DPSContext ctxt; 7); 

extern void DPSputinterval( /* DPSContext ctxt; 7); 
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extern void DPSquit( /* DPSContext ctxt; 7); 

extern void DPSrand( /* DPSContext ctxt; 7); 

extern void DPSrcheck( /* DPSContext ctxt; int *b; 7); 

extern void DPSrcurveto( /* DPSContext ctxt; float xl, yl, x2, y2, x3, y3; 7); 

extern void DPSread( /* DPSContext ctxt; int *b; 7); 

extern void DPSreadhexstring( I* DPSContext ctxt; int *b; 7); 

extern void DPSreadline( /* DPSContext ctxt; int *b; 7); 

extern void DPSreadonly( /* DPSContext ctxt; 7); 

extern void DPSreadstring( /* DPSContext ctxt; int *b; 7); 

extern void DPSrealtime( /* DPSContext ctxt; int *i; 7); 

extern void DPSrectclip( /* DPSContext ctxt; float x, y, w, h; 7); 

extern void DPSrectfill( /* DPSContext ctxt; float x, y, w, h; 7); 

extern void DPSrectstroke( /* DPSContext ctxt; float x, y, w, h; 7); 

extern void DPSrectviewelip( /* DPSContext ctxt; float x, y, w, h; 7); 

extern void DPSrenamefile(/* DPSContext ctxt; char *old, *new; 7); 

extern void DPSrenderbands( /* DPSContext ctxt; 7); 

extern void DPSrepeat( /* DPSContext ctxt; 7); 

extern void DPSresetfile( /* DPSContext ctxt; 7); 

extern void DPSrestore( /* DPSContext ctxt; 7); 

extern void DPSreversepath( /* DPSContext ctxt; 7); 

extern void DPSrlineto( /* DPSContext ctxt; float x, y; 7); 

extern void DPSrmoveto( /* DPSContext ctxt; float x, y; 7); 

extern void DPSroll( /* DPSContext ctxt; int n, j; 7); 

extern void DPSrotate( /* DPSContext ctxt; float angle; 7); 

extern void DPSround( /* DPSContext ctxt; 7); 

extern void DPSrrand( /* DPSContext ctxt; 7); 

extern void DPSrun( /* DPSContext ctxt; char ‘filename; 7); 

extern void DPSsave( /* DPSContext ctxt; 7); 

extern void DPSscale( /* DPSContext ctxt; float x, y; 7); 

extern void DPSscalefont( /* DPSContext ctxt; float size; 7); 
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extern void DPSscheck( /* DPSContext ctxt; int *b; 7); 

extern void DPSsearch( /* DPSContext ctxt; int *b; 7); 

extern void DPSselectfont( /* DPSContext ctxt; char 'name; float scale; 7); 

extern void DPSsendboolean( /* DPSContext ctxt; int it; 7); 

extern void DPSsendchararray( /* DPSContext ctxt; char s[]; int size; 7); 

extern void DPSsendfloat( f DPSContext ctxt; float it; 7); 

extern void DPSsendfloatarray( /* DPSContext ctxt; float a[]; int size; 7); 

extern void DPSsendint( /* DPSContext ctxt; int it; 7); 

extern void DPSsendintarray( /* DPSContext ctxt; int aQ; int size; 7); 

extern void DPSsendstring( /* DPSContext ctxt; char *s; 7); 

extern void DPSsetbbox( /* DPSContext ctxt; float llx, lly, urx, ury; 7); 

extern void DPSsetblackgeneration( /* DPSContext ctxt; 7); 

extern void DPSsetcachedevice( /* DPSContext ctxt; float wx, wy, llx, lly, urx, ury; 7); 

extern void DPSsetcachelimit{ /* DPSContext ctxt; float n; 7); 

extern void DPSsetcacheparams( /* DPSContext ctxt; 7); 

extern void DPSsetcharwidth( /* DPSContext ctxt; float wx, wy; 7); 

extern void DPSsetcmykcolor( /* DPSContext ctxt; float c, m, y, k; 7); 

extern void DPSsetcolorscreen( /* DPSContext ctxt; 7); 

extern void DPSsetcolortransfer( /* DPSContext ctxt; 7); 

extern void DPSsetdash( /* DPSContext ctxt; float patQ; int size; float offset; 7); 

extern void DPSsetfileposition( /* DPSContext ctxt; int pos; 7); 

extern void DPSsetflat( /* DPSContext ctxt; float flatness; 7); 

extern void DPSsetfont( /* DPSContext ctxt; int f; 7); 

extern void DPSsetgray( /* DPSContext ctxt; float gray; 7); 

extern void DPSsetgstate( /* DPSContext ctxt; int gst; 7); 

extern void DPSsethalftone( /* DPSContext ctxt; 7); 

extern void DPSsethalftonephase( /* DPSContext ctxt; float x, y; 7); 

extern void DPSsethsbcolor( /* DPSContext ctxt; float h, s, b; 7); 

extern void DPSsetlinecap( /* DPSContext ctxt; int linecap; 7); 

extern void DPSsetlinejoin( /* DPSContext ctxt; int linejoin; 7); 
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extern void DPSsetlinewidth( /* DPSContext ctxt; float width; 7); 

extern void DPSsetmatrix( /* DPSContext ctxt; 7); 

extern void DPSsetmiterlimit(/* DPSContext ctxt; float limit; 7); 

extern void DPSsetobjectformat(/* DPSContext ctxt; int code; 7); 

extern void DPSsetpacking( /* DPSContext ctxt; int b; 7); 

extern void DPSsetrgbcolor( /* DPSContext ctxt; float r, g, b; 7); 

extern void DPSsetscreen( /* DPSContext ctxt; 7); 

extern void DPSsetshared( /* DPSContext ctxt; int b; 7); 

extern void DPSsetstrokeadjust( /* DPSContext ctxt; int b; 7); 

extern void DPSsettransfer( /* DPSContext ctxt; 7); 

extern void DPSsetucacheparams(/* DPSContext ctxt; 7); 

extern void DPSsetundercolorremoval( /* DPSContext ctxt; 7); 

extern void DPSsetvmthreshold( /* DPSContext ctxt; int i; 7); 

extern void DPSshareddict( /* DPSContext ctxt; 7); 

extern void DPSshow( /* DPSContext ctxt; char *s; 7); 

extern void DPSshowpage( /* DPSContext ctxt; 7); 

extern void DPSsin( /* DPSContext ctxt; 7); 

extern void DPSsqrt( /* DPSContext ctxt; 7); 

extern void DPSsrand( /* DPSContext ctxt; 7); 

extern void DPSstack( /* DPSContext ctxt; 7); 

extern void DPSstart( /* DPSContext ctxt; 7); 

extern void DPSstatus( /* DPSContext ctxt; int *b; 7); 

extern void DPSstatusdict( /* DPSContext ctxt; 7); 

extern void DPSstop( /* DPSContext ctxt; 7); 

extern void DPSstopped( I* DPSContext ctxt; 7); 

extern void DPSstore( /* DPSContext ctxt; 7); 

extern void DPSstring( /* DPSContext ctxt; int len; 7); 

extern void DPSstringwidth( /* DPSContext ctxt; char *s; float *xp, *yp; 7); 

extern void DPSstroke( /* DPSContext ctxt; 7); 

extern void DPSstrokepath( /* DPSContext ctxt; 7); 
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extern void DPSsub( /* DPSContext ctxt; 7); 

extern void DPSsystemdict( /* DPSContext ctxt; 7); 

extern void DPStoken( /* DPSContext ctxt; int *b; 7); 

extern void DPStransform( /* DPSContext ctxt; float xl, yl; float *x2, *y2; 7); 

extern void DPStranslate( /* DPSContext ctxt; float x, y; 7); 

extern void DPStrue( /* DPSContext ctxt; 7); 

extern void DPStruncate( /* DPSContext ctxt; 7); 

extern void DPStype( /* DPSContext ctxt; 7); 

extern void DPSuappend( /* DPSContext ctxt; char nums[]; int n; char ops[]; int I; 7); 
extern void DPSucache( /* DPSContext ctxt; 7); 
extern void DPSucachestatus( /* DPSContext ctxt; 7); 

extern void DPSueofill( /* DPSContext ctxt; char nums[]; int n; char ops[]; int I; 7); 

extern void DPSufill( /* DPSContext ctxt; char nums[]; int n; char ops[]; int I; 7); 

extern void DPSundeff /* DPSContext ctxt; char ‘name; 7); 

extern void DPSundefinefont( /* DPSContext ctxt; char ‘name; 7); 

extern void DPSundefineuserobject( /* DPSContext ctxt; int userObjlndex; 7); 

extern void DPSupath( /* DPSContext ctxt; int b; 7); 

extern void DPSuserdict( /* DPSContext ctxt; 7); 

extern void DPSusertimef /* DPSContext ctxt; int ‘milliseconds; 7); 

extern void DPSustroke( /* DPSContext ctxt; char nums[]; int n; char ops[]; int I; 7); 

extern void DPSustrokepath( /* DPSContext ctxt; char nums[]; int n; char ops[]; int I; 7); 

extern void DPSversion( /* DPSContext ctxt; int bufsize; char buf[]; 7); 

extern void DPSviewclip( /* DPSContext ctxt; 7); 

extern void DPSviewclippath( /* DPSContext ctxt; 7); 

extern void DPSvmreclaimf /* DPSContext ctxt; int code; 7); 

extern void DPSvmstatus( /* DPSContext ctxt; int ‘level, ‘used, ‘maximum; 7); 

extern void DPSwait( /* DPSContext ctxt; 7); 

extern void DPSwcheck( /* DPSContext ctxt; int *b; 7); 

extern void DPSwhere( /* DPSContext ctxt; int *b; 7); 

extern void DPSwidthshow( /* DPSContext ctxt; float x, y; int c; char *s; 7); 


10 SINGLE-OPERATOR PROCEDURES 


71 




extern void DPSwrite( /* DPSContext ctxt; 7); 

extern void DPSwritehexstring( /* DPSContext ctxt; 7); 

extern void DPSwriteobject( /* DPSContext ctxt; int tag; 7); 

extern void DPSwritestring( /* DPSContext ctxt; 7); 

extern void DPSwtranslation( /* DPSContext ctxt; float *x, *y; 7); 

extern void DPSxcheck( /* DPSContext ctxt; int *b; 7); 

extern void DPSxor(/* DPSContext ctxt; 7); 

extern void DPSxshow( /* DPSContext ctxt; char *s; float numarray[]; int size; 7); 
extern void DPSxyshow( /* DPSContext ctxt; char *s; float numarray[]; int size; 7); 
extern void DPSyield( /* DPSContext ctxt; 7); 

extern void DPSyshow( I* DPSContext ctxt; char *s; float numarray[]; int size; 7); 
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11 RUNTIME SUPPORT FOR WRAPPED PROCEDURES 


This section describes the procedures in the dpsfriends.h header 
file that are called by wrapped procedures — the C-callable 
procedures that are output by the pswrap translator. This infor¬ 
mation is not normally required by the application programmer. 

A description of the dpsfriends.h header file is provided for ap¬ 
plication or toolkit programmers who need finer control over 
these areas: 

• Transmission of code for execution. 

• Handling of result values. 

• Mapping of user names to user name indices. 

This section also contains a discussion of the structure of binary 
object sequences. 

11.1 MORE ABOUT SENDING CODE FOR EXECUTION 

One of the primary purposes of the Client Library is to provide 
runtime support for the code generated by pswrap. Each wrapped 
procedure builds a binary object sequence that represents the 
PostScript language code to be executed. Since a binary object 
sequence is structured, the procedures for sending a binary object 
sequence are designed to take advantage of this structure. 

The following procedures efficiently process binary object se¬ 
quences generated by wrapped procedures: 

• DPSBinObjSeqWrite sends the beginning of a new binary 
object sequence generated by a wrapped procedure. This 
initial part includes, at minimum, the header and the entire 
top-level sequence of objects. It can also include sub¬ 
sidiary array elements and/or string characters if those ar¬ 
rays and strings are static — that is, if their lengths are 
known at compile time and there are no intervening arrays 
or strings of varying length. DPSBinObjSeqWrite may 
convert the binary object sequence to another encoding, 
depending upon the ‘DPSContextRec’ encoding variables. 
For a particular wrapped procedure, DPSBinObjSeqWrite is 
called exactly once. 


11 RUNTIME SUPPORT FOR WRAPPED PROCEDURES 


73 



• DPSWriteTypedObjectArray sends arrays (excluding 
strings) that were specified as input arguments to a 
wrapped procedure. It writes PostScript language code 
specified by the context’s format and encoding variables, 
doing appropriate conversions as needed. For a particular 
wrapped procedure, DPSWriteTypedObjectArray is called 
zero or more times — once for each input array specified. 

• DPSWriteStringChars sends the text of strings or names. It 
appends characters to the current binary object sequence. 
For a particular wrapped procedure, DPSWriteStringChars 
is called zero or more times to send the text of names and 
strings. 

The overall length of arrays and strings sent by 
DPSWriteTypedObjectArray and DPSWriteStringChars must be 
consistent with the length information specified in the binary ob¬ 
ject sequence header sent by DPSBinObjSeqWrite. In particular, 
don’t rely on ‘sizeof()’ to return the correct size value of the 
binary object sequence. 

11.2 RECEIVING RESULTS 

Each wrapped procedure with output arguments constructs an 
array containing elements of type ‘DPSResultsRec’. This array 
is called the result table. The index position of each element cor¬ 
responds to the ordinal position of each output argument as 
defined in the wrapped procedure: the first table entry (index 0) 
corresponds to the first output argument, the second table entry 
(index 1) corresponds to the second argument, and so on. Each 
entry defines one of the output arguments of a wrapped proce¬ 
dure by specifying a data type, a count, and a pointer to the 
storage for the value. DPSSetResultTable registers the result 
table with the context. 

The interpreter sends return values to the application as binary 
object sequences. Wrapped procedures that have output argu¬ 
ments use the printobject operator to tag and send each return 
value. (See the discussion of the printobject operator in 
PostScript Language Extensions for the Display PostScript 
System .) The tag corresponds to the index of the output argument 
in the result table. After the wrapped procedure finishes sending 
the PostScript language program, it calls DPSAwaitReturnValues 
to wait for all of the results to come back. 
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As the Client Library receives results from the interpreter, it 
places each result into the output argument specified by the 
result table. The tag of each result object in the sequence is used 
as an index into the result table. When the Client Library 
receives a tag that is greater than the last defined tag number, 
DPSAwaitReturnValues returns. This final tag is called the ter¬ 
mination tag. 

Certain conventions must be followed to handle return values for 
wrapped procedures properly: 

• The tag associated with the return value is the ordinal of the 
output parameter as listed in the definition of the wrapped 
procedure, starting from 0 and counting from left to right 
(see example below). 

• If the ‘count’ field of the ‘DPSResultsRec’ is -1, the ex¬ 
pected result is a single element, or “scalar,” and return 
values with the same tag overwrite previous values. Other¬ 
wise, the ‘count’ indicates the number of array elements 
that remain to be received. In this case, a series of return 
values with the same tag are stored in successive elements 
of the array. If the value of ‘count’ is zero, further array 
elements of the same tag value are ignored. 

• DPSAwaitReturnValues returns when it notices that the 
‘resuItTable’ pointer in the ‘DPSContextRec’ data object is 
‘NULL’. The code that handles return values should note 
the reception of the termination tag by setting the 
‘resuItTable’ to ‘NULL’ to indicate that there are no more 
return values to receive for this wrapped procedure. 

Here is an example of a wrap with return values: 

defineps Example(l int *x, *y, *z) 

10 20 30 x y z 
endps 

The code generated for this wrapped procedure is actually: 
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10 20 30 
0 printobject 

% pop integer 30 off the operand stack, 

% use tag = 0 (result table index = 0, first parameter ’x’) 

% write binary object sequence 

1 printobject 

% pop integer 20 off the operand stack, 

% use tag = 1 (result table index = 1, second parameter ’y’) 
% write binary object sequence 

2 printobject 

% pop integer 10 off the operand stack, 

% use tag = 2 (result table index = 2, third parameter ’z’) 

% write binary object sequence 
0 3 printobject 

% push dummy value 0 on operand stack 
% pop integer 0 off operand stack, 

% use tag = 3 (termination tag) 

% write binary object sequence 
flush 

% make sure all data is sent back to the application 


11.3 MANAGING USER NAMES 

Name indices are the most efficient way to specify names in a 
binary object sequence; refer to PostScript Language Extensions 
for the Display PostScript System for a full description. The 
Client Library manages the mapping of user names to indices. 
Wrapped procedures map user names automatically. The first 
time a wrapped procedure is called, it calls DPSMapNames to 
map all user names specified in the wrapped procedure into in¬ 
dices. The application may also call DPSMapNames directly to 
obtain name mappings. 

A name map is stored in a space. All contexts associated with 
that space have the same name map. The name mapping for the 
context is automatically kept up to date by the Client Library in 
the following way: 

• Every wrapped procedure calls DPSBinObjSeqWrite, 
which, in addition to sending the binary object sequence, 
checks to see if the user name map is up to date. 

• DPSBinObjSeqWrite calls DPSUpdateNameMap if the 
name map of the space does not agree with the Client 
Library’s name map. DPSUpdateNameMap may send a 
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series of defineusername operators to the PostScript inter¬ 
preter. 

DPSNameFromlndex returns the text for the user name with the 
given index. The string returned is owned by the Client Library; 
treat it as read-only. 

11.4 BINARY OBJECT SEQUENCES 

Syntactically, a binary object sequence is a single token. The 
structure is described in detail in PostScript Language Exten¬ 
sions for the Display PostScript System. The definitions in this 
section correspond to the components of a binary object se¬ 
quence. 

#define DPS_HEADER_SIZE 4 


#define DPSJHIJEEE 128 

#define DPSJ.OJEEE 129 

#define DPS_HI_NATIVE 130 

#define DPS_LO_NATIVE 131 


#ifndef DPS_DEF_TOKENTYPE 

#define DPS_DEF_TOKENTYPE DPS_HI_IEEE 

#endif DPS_DEF_TOKENTYPE 

typedef struct { 

unsigned char tokenType; 
unsigned char nTopElements; 
unsigned short length; 

DPSBinObjRec objects[1 ]; 

} DPSBinObjSeqRec, *DPSBinObjSeq; 

A binary object sequence begins with a four-byte header. The 
first byte indicates the token type. A binary object is defined by 
one of the four token type codes listed above. 
‘DPS_DEF_TOKENTYPE’ defines the default token type for bi¬ 
nary object sequences generated by a particular implementation 
of the Client Library. ‘DPS_DEF_TOKENTYPE’ must be consis¬ 
tent with the machine architecture upon which the Client Library 
is implemented. 

The ‘nTopElements’ byte indicates the number of top-level ob¬ 
jects in the sequence. A binary object sequence can have from 1 
to 255 top-level objects. If more top-level objects are required, 
use an extended binary object sequence (described in Section 
11.5). 
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The next two bytes form a nonzero 16-bit integer that is the total 
byte length of the binary object sequence. 

The header is followed by a sequence of objects. 


#define DPS_NULL 0 

#define DPSJNT 1 

#define DPS_REAL 2 

#define DPS_NAME 3 

#define DPS_BOOL 4 

#define DPS_STRING 5 

#define DPSJMMEDIATE 6 

#define DPS_ARRAY 9 

#define DPS_MARK 10 


The first byte of an object describes its attributes and type. The 
types are listed above and correspond to the PostScript language 
objects that pswrap generates. 

#define DPSJJTERAL 0 
#define DPS.EXEC 0x080 

The high-order bit indicates whether the object has the literal (0) 
or executable (1) attribute. 

The next byte is the tag byte, which must be zero for objects sent 
to the interpreter. Result values sent back from the interpreter 
will use the tag field, as described in Section 11.2. 

The next two bytes form a 16-bit integer that is the length of the 
object. The unit value of the length field depends upon the type 
of the object. For arrays, the length indicates the number of ele¬ 
ments in the array. For strings, the length indicates the number of 
characters. 

The last four bytes of the object form the value field. The inter¬ 
pretation of this field depends upon the type of the object. 
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typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
short length; 
long int val; 

} DPSBinObjGeneric; /* boolean, int, string, name and array 7 

typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
short length; 
float realVal; 

} DPSBinObjReal; /* float */ 

‘DPSBinObjGeneric’ and ‘DPSBinObjReal’ are defined for the 
use of wraps. They make it easier to initialize the static portions 
of the binary object sequence. 

typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
short length; 
union { 

long int integerVal; 
float realVal; 

long int nameVal; /* offset or index 7 
long int booleanVal; 
long int stringVal; /* offset 7 
long int arrayVal; /* offset 7 
} val; 

} DPSBinObjRec; 

‘DPSBinObjRec’ is a general-purpose variant record for inter¬ 
preting an object in a binary object sequence. 

11.5 EXTENDED BINARY OBJECT SEQUENCES 

An extended binary object sequence is required if there are more 
than 255 top-level objects in the sequence. The extended binary 
object sequence is represented by 

‘DPSExtendedBinObjSeqRec’, as follows: 

Byte 0 Same as for a normal binary object sequence; it 

represents the token type. 

Byte 1 Set to zero; indicates that this is an extended bi¬ 

nary object sequence. (In a normal binary object 
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sequence, this byte represents the number of top- 
level objects.) 

Bytes 2-3 A 16-bit value representing the number of top- 
level elements. 

Bytes 4-7 A 32-bit value representing the overall length of 
the extended binary object sequence. 

The byte order in numeric fields is according to the number rep¬ 
resentation specified by the token type. 

The layout of the remainder of the extended binary object se¬ 
quence is identical to that of a normal binary object sequence. 

11.6 DPSFRIENDS.H DATA STRUCTURES 

This section describes the data structures used by the pswrap 
program as part of its support for wrapped procedures. 


Note: The ‘DPSContextRec’ data structure and its handle, 
‘DPSContext’, are part of the dpsfriends.h header file. They are 
documented in Section 9.1 because they are also used by 
dpsclient.h procedures. 


DPSBinObjGeneric 

typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
unsigned short length; 
long int val; 

} DPSBinObjGeneric; /* boolean, int, string, name and array */ 

is defined for the use of wraps. It is used to initialize the static 
portions of the binary object sequence. See ‘DPSBinObjReaP for 
type ‘real’. 
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DPSBinObjReal 


DPSBinObjRec 


DPSBinObjSeqRec 


typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
unsigned short length; 
float realVal; 

} DPSBinObjReal; /* float 7 

is similar to ‘DPSBinObjGeneric’, but represents a real number. 


typedef struct { 

unsigned char attributedType; 
unsigned char tag; 
unsigned short length; 
union { 

long int integerVal; 
float realVal; 

long int nameVal; /* offset or index 7 
long int booleanVal; 
long int stringVal; /* offset 7 
long int arrayVal; /* offset 7 
} val; 

} DPSBinObjRec; 

is a general-purpose variant record for interpreting an object in a 
binary object sequence. 


typedef struct { 

unsigned chartokenType; 
unsigned char nTopElements; 
unsigned short length; 

DPSBinObjRec objects[1j; 

} DPSBinObjSeqRec. *DPSBinObjSeq; 

This data type is provided as a convenience for accessing a bi¬ 
nary object sequence copied from an I/O buffer. 
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DPSDefinedType typedefenum{ 
dpsJBoolean, 
dpsjChar, dpsjUChar, 
dps_tFloat, dps_tDouble, 
dps_tShort, dpsjUShort, 
dpsjlnt, dps_tUlnt, 

dpsjLong, dpsjULong} DPSDefinedType; 
enumerates the C data types used to describe wrap arguments. 


DPSExtendedBinObjSeqRec 

typedef struct { 

unsigned char tokenType; 

unsigned char escape; /* zero if this is an extended sequence 7 
unsigned short nTopElements; 
unsigned long length; 

DPSBinObjRec objects[1]; 

} DPSExtendedBinObjSeqRec, ’DPSExtendedBinObjSeq; 

This data type has a purpose similar to ‘DPSBinObjSeqRec’, but 
is used for extended binary object sequences. 


DPSNameEncoding 

typedef enum { 
dpsjndexed, dps_strings 
} DPSNameEncoding; 

defines the two possible encodings for user names in the 
‘dps_binObjSeq’ and ‘dps_encodedTokens’ forms of PostScript 
language programs. 


DPSProcs I* pointer to procedures record 7 

See ‘DPSProcsRec’. 
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DPSProcsRec 


typedef struct { 

void (*BinObjSeqWrite)( /* DPSContext ctxt, char *buf, unsigned int count 7); 
void (*WriteTypedObjectArray)( /* 

DPSContext ctxt, 

DPSDefinedType type; 
char *array, 
unsigned int length */); 

void (*WriteStringChars)( /* DPSContext ctxt; char *buf; unsigned int count; 7); 

void (*WriteData)( /* DPSContext ctxt, char *buf, unsigned int count 7); 

void (*WritePostScript)( /* DPSContext ctxt, char *buf, unsigned int count 7); 

void (*FlushContext)( /* DPSContext ctxt 7); 

void (*ResetContext)( /* DPSContext ctxt 7); 

void (*UpdateNameMap)( /* DPSContext ctxt 7); 

void (*AwaitReturnValues)( /* DPSContext ctxt 7); 

void ('Interrupt)! /* DPSContext ctxt 7); 

void (*DestroyContext)( /* DPSContext ctxt 7); 

void (*WaitContext)( /* DPSContext ctxt 7); 

} DPSProcsRec, 'DPSProcs; 

defines the data structure pointed to by ‘DPSProcs’. 

This record contains pointers to procedures that implement all of 
the operations that can be performed on a context. These 
procedures are analogous to the instance methods of an object in 
an object-oriented language. 


Note: Application developers need not be concerned with the 
contents of this data structure. Do not change the ‘DPSProcs’ 
pointer. Do not change the contents of ‘DPSProcsRec’. 


DPSProgramEncoding 

typedef enum { 

dps_ascii, dps_binObjSeq, dps_encodedTokens 
} DPSProgramEncoding; 

defines the three possible encodings of PostScript language 
programs: ASCII encoding, binary object sequence encoding, 
and binary token encoding. 
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DPSResultsRec 


DPSSpace 


DPSSpaceRec 


11.7 


typedef struct { 

DPSDefinedType type; 
int count; 
char 'value; 

} DPSResultsRec, 'DPSResults; 

Each wrapped procedure constructs an array called the result 
table, which consists of elements of type ‘DPSResultsRec’. The 
index position of each element corresponds to the ordinal posi¬ 
tion of each output parameter as defined in the wrapped proce¬ 
dure; for example, index 0 (the first table entry) corresponds to 
the first output parameter, index 1 corresponds to the second out¬ 
put parameter, and so on. 

‘type’ specifies the formal type of the return value, ‘count’ 
specifies the number of values expected; this supports array for¬ 
mats. ‘value’ points to the location of the first value; the storage 
beginning there must have room for ‘count’ values of type 
‘type’. If ‘count’ is -1, ‘value’ points to a scalar (single) result 
argument. If ‘count’ is zero, any subsequent return values are 
ignored. 


/* handle for space record 7 
See ‘DPSSpaceRec’. 


typedef struct { 

DPSSpaceProcs procs; 

} DPSSpaceRec, 'DPSSpace; 

typedef struct { 

void (*DestroySpace)(/* DPSSpace space 7); 

} DPSSpaceProcsRec, 'DPSSpaceProcs; 

provides a representation of a space. See also DPSDestroySpace 
in Section 9.2. 


DPSFRIENDS.H PROCEDURES 

The following is an alphabetical listing of the procedures in the 
Client Library header file dpsfriends.h. These procedures are for 
experts only; most application programmers don’t need them. 
The pswrap translator inserts calls to these procedures when it 
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creates C-callable wrapped procedures specified by the applica¬ 
tion programmer. 

DPSAwaitReturnValues 

void DPSAwaitRetumValues(ctxt) 

DPSContext ctxt; 

waits for all results described by the result table; see 
‘DPSResultRec’. It uses the tag of each object in the sequence to 
find the corresponding entry in the result table. When 
DPSAwaitReturnValues receives a tag that is greater than the last 
defined tag number, there are no more return values to be 
received and the procedure returns. This final tag is called the 
termination tag. DPSSetResultTable must be called to set the 
result table before any calls to DPSBinObjSeqWrite. 

DPSAwaitReturnValues can call the context’s error procedure 
with ‘dps_err_resultTagCheck’ or ‘dps_err_resultTypeCheck\ It 
will return prematurely if it encounters a ‘dps_err_ps’ error. 


DPSBinObjSeqWrite 

void DPSBinObjSeqWrite(ctxt, buf, count) 

DPSContext ctxt; 
char *buf; 
unsigned int count; 

sends the beginning of a binary object sequence generated by a 
wrap, ‘buf points to a buffer containing ‘count’ bytes of a binary 
object sequence, ‘but’ must point to the beginning of a sequence, 
which includes at least the header and the entire top-level se¬ 
quence of objects. 

DPSBinObjSeqWrite may also include subsidiary array elements 
and/or strings. It writes PostScript language as specified by the 
format and encoding variables of ‘ctxt’, doing appropriate con¬ 
versions as needed. If the buffer does not contain the entire bi¬ 
nary object sequence, one or more calls to 
DPSWriteTypedObjectArray and/or DPSWriteStringChars must 
follow immediately; ‘buf’ and its contents must remain valid un¬ 
til the entire binary object sequence has been written. 
DPSBinObjSeqWrite ensures that the user name map is up to 
date. 
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DPSMapNames 


void DPSMapNames(ctxt, nNames, names, indices) 

DPSContext ctxt; 
unsigned int nNames; 
char “names; 
long int "‘indices; 

maps all specified names into user name indices, sending new 
defineusername definitions as needed, ‘names’ is an array of 
strings whose elements are the user names. ‘nNames’ is the 
number of elements in the array, ‘indices’ is an array of pointers 
to ‘(long int *)’ integers, which are the locations in which to store 
the indices. DPSMapNames is normally called automatically 
from within wraps. The application can also call this procedure 
directly to obtain name mappings. 

DPSMapNames calls the context’s error procedure with 
‘ dps_err_nameT ooLong’. 


Note: The caller must ensure that the string pointers remain 
valid after the procedure returns. The Client Library becomes 
the owner of all strings passed to it with DPSMapNames. 


The same name may be used several times in a wrap. To reduce 
string storage, these duplicates can be eliminated by using an 
optimization recognized by DPSMapNames. If the pointer to the 
string in the array ‘names’ is null — that is, ‘(char *)0’ — 
DPSMapNames uses the nearest non-null name that precedes the 
‘(char *)0’ entry in the array. The first element of ‘names’ must 
be non-null. This optimization works best if you sort the names 
so that duplicate occurrences are adjacent. 


Example: DPSMapNames treats the following arrays as equiv¬ 
alent, but the one on the right saves storage. 


{ 

“boxes", 

“drawMe”, 

"drawMe", 

"init", 

"makeAPath", 

"retumAClip", 

"retumAClip", 

"retumAClip" 

} 


{ 

"boxes", 
"drawMe", 
(char *)0, 
“init", 

“makeAPath", 
“retumAClip", 
(char *)0, 
(char *)0 
} 
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DPSNameFromlndex 

char *DPSNameFromlndex(index) 
long int index; 

returns the text for the user name with the given index. The 
string returned must be treated as read-only. ‘NULL’ will be 
returned if ‘index’ is invalid. 


DPSSetResuItTable 

void DPSSetResultTable(ctxt, tbl, len) 

DPSContext ctxt; 

DPSResults tbl; 
unsigned int len; 

sets the result table and its length in ‘ctxt’. This operation must 
be performed before a wrap body that can return a value is sent 
to the interpreter. 


DPSUpdateNameMap 

void DPSUpdateNameMap(ctxt) 

DPSContext ctxt; 

sends a series of defineusername commands to the interpreter. 
This procedure is called if the name map of the context’s space is 
not synchronized with the Client Library name map. 


DPSWriteStringChars 

void DPSWriteStringChars(ctxt, but, count); 

DPSContext ctxt; 
char *buf; 
unsigned int count; 

appends strings to the current binary object sequence, ‘but’ con¬ 
tains ‘count’ characters that form the body of one or more strings 
in a binary object sequence, ‘but’ and its contents must remain 
valid until the entire binary object sequence has been sent. 
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DPSWriteTypedObject Array 

void DPSWriteTypedObjectArray(ctxt, type, array, length) 

DPSContext ctxt; 

DPSDefinedType type; 
char 'array; 
unsigned int length; 

writes PostScript language code as specified by the format and 
encoding variables of ‘ctxt’, doing appropriate conversions as 
needed, ‘array’ points to an array of ‘length’ elements of type 
‘type’, ‘array’ contains the element values for the body of a sub¬ 
sidiary array that was passed as an input argument to pswrap. 
‘array’ and its contents must remain valid until the entire binary 
object sequence has been sent. 
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A CHANGES SINCE LAST PUBLICATION OF THIS DOCUMENT 


Changes to the Client Library Reference Manual from the docu¬ 
ment dated October 25,1989, are noted in the paragraphs below. 

Input sent to a child context is not passed to its parent. 

In calls to DPSWriteData, the contents of the buffer will not be 
converted according to the context’s encoding parameters. 

A few additional minor amplifications and corrections have been 
made. 

Changes to the Client Library Reference Manual from the docu¬ 
ment dated October 7, 1988, are noted in the paragraphs below. 

The manual has been completely reorganized and rewritten. 

An example error handler program, DPSDefaultErrorProc, has 
been provided in Appendix B. This is the default error handler in 
the Display PostScript extension for the X Window System. 

The synchronization example in Section 6.4 has been replaced 
by an X-specific example. 

The specifications for dpsclient.h and clpsfriends.h procedures 
are now in separate chapters. 

Listings of the header files have been removed, except for 
dpsops.h (representing itself and psops.h), whose procedure 
declarations are not listed elsewhere in this manual. 

Numerous inconsistencies in the arguments to some of the 
single-operator procedures have been cleaned up. 

The document has been updated to be consistent with the latest 
versions of dpsfriends.h, dpsclient.h, dpsops.h, and psops.h. The 
following are no longer defined by Adobe: 

• DPSGetLastNamelndex 

• DPSLastNamelndex 

• DPSLastObjectlndex 

• DPSNewUser Object 
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References to system-specific issues have been added throughout 
the manual, including the following: 

• Context creation routines. 

• Behavior of default and backstop error and text handlers. 

• Automatic encoding translation (for example, binary object 
sequence to tokens). 

• Additional error codes. 

• Exception handling and error recovery. 

• Programming examples and code fragments. 

A section on programming tips has been added. 

The index has been enhanced. 
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B EXAMPLE ERROR HANDLER 


An error handler must deal with all errors defined in dpsclient.h 
as well as any additional errors defined in system-specific header 
files. 

This appendix contains an example of an error handler for the X 
Window System extension of the Display PostScript system. 


B.1 ERROR HANDLER IMPLEMENTATION 

An example implementation of an error handler, 
DPSDefaultErrorProc, follows. The code is followed by ex¬ 
planatory text. 


#include "dpsclient.h" 
void 

DPSDefaultErrorProc(ctxt, errorCode, argl, arg2) 

DPSContext ctxt; 

DPSErrorCode errorCode; 
long unsigned int argl, arg2; { 

DPSTextProc textProc = DPSGetCurrentTextBackstopO; 

char "prefix = "%%[ Error: 
char "suffix =" ]%%\n"; 

char "infix = OffendingCommand:"; 

char "nameinfix = "User name too long; Name:"; 

char "contextinfix = "Invalid context: ’; 

char "taginfix = "Unexpected wrap result tag: "; 

char "typeinfix = "Unexpected wrap result type; tag: “; 

switch (errorCode) { 
case dps_err_ps: { 
char "buf = (char *)arg1; 

DPSBinObj ary = (DPSBinObj) (buf+DPS_HEADER_SIZE); 

DPSBinObj elements; 

char "error, "errorName; 

integer errorCount, errorNameCount; 

boolean resyncFIg; 

Assert((ary->attributedType & 0x7f) == DPS_ARRAY); 
Assert(ary->length == 4); 

elements = (DPSBinObj)(((char *) ary) + ary->val.arrayVal); 
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errorName = (char *)(((char *) ary) + elements[1].val.nameVal); 
errorNameCount = elements[1].length; 

error = (char *)(((char *) ary) + elements[2].val.nameVal); 
errorCount = elements[2]. length; 

resyncFIg = elements[3].val.booleanVal; 

if (textProc != NIL) { 

(*textProc)(ctxt, prefix, strlen(prefix)); 

(*textProc)(ctxt, errorName, errorNameCount); 

(*textProc)(ctxt, infix, strlen(infix)); 

(*textProc)(ctxt, error, errorCount); 

(*textProc)(ctxt, suffix, strlen(suffix)); 

} 

if (resyncFIg && (ctxt != dummyCtx)) { 

RAISE(dps_err_ps, ctxt); 

CantHappen(); 

} 

break; 

} 

case dps_err_nameTooLong: 
if (textProc != NIL) { 
char *buf = (char *)arg1; 

(*textProc)(ctxt, prefix, strlen(prefix)); 

(*textProc)(ctxt, nameinfix, strlen(nameinfix)); 

(*textProc)(ctxt, buf, arg2); 

(‘textProc)(ctxt, suffix, strlen(suffix)); 

} 

break; 

case dps_err_invalidContext: 
if (textProc != NIL) { 
char m[100]; 

(void) sprintf(m, "%s%s%d%s", prefix, contextinfix, argl, suffix); 
(*textProc)(ctxt, m, strlen(m)); 

} 

break; 

case dps_err_resultTagCheck: 
case dps_err_resultTypeCheck: 
if (textProc != NIL) { 
char m[100]; 

unsigned char tag = ‘((unsigned char *) argl+1); 

(void) sprintf(m, "%s%s%d%s“, prefix, typeinfix, tag, suffix); 
(*textProc)(ctxt, m, strlen(m)); 

} 

break; 

case dps_err_invalidAccess: 
if (textProc != NIL) 

{ 

charm[100]; 


92 


Client Library Reference Manual / Version of January 23,1990 



(void) sprintf (m, "%slnvalid context access.%s", prefix, suffix); 
(‘textProc) (ctxt, m, strlen (m)); 

} 

break; 

case dps_err_encodingCheck: 
if (textProc != NIL) 

{ 

char m[100]; 

(void) sprintf (m, "%slnvalid name/program encoding: %d/%d.%s", 
prefix, (int) argl, (int) arg2, suffix); 

(‘textProc) (ctxt, m, strlen (m)); 

} 

break; 

case dps_err_closedDisplay: 
if (textProc != NIL) 

{ 

char m[100]; 

(void) sprintf (m, "%sBroken display connection %d.%s", 
prefix, (int) argl, suffix); 

(‘textProc) (ctxt, m, strlen (m)); 

} 

break; 

case dps_err_deadContext: 
if (textProc != NIL) 

{ 

char m[100]; 

(void) sprintf (m, "%sDead context OxO%x.%s", prefix, 

(int) argl, suffix); 

(‘textProc) (ctxt, m, strlen (m)); 

} 

break; 

default:; 

} 

} /* DPSDefaultErrorProc 7 


B.2 DESCRIPTION OF THE ERROR HANDLER 

DPSDefaultErrorProc handles errors that arise when a wrap or 
Client Library procedure is called for the context. The error code 
indicates what error occurred. Interpretation of the ‘argl’ and 
l arg2’ values is based on the error code. 

The error handler initializes itself by getting the current backstop 
text handler and assigning string constants that will be used to 
formulate and report a text message. The section of the program 
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that deals with the various error codes begins with the ‘switch’ 
statement. Each error code can be handled differently. 

If a ‘textProc’ was specified, the error handler calls the text 
handler to formulate an error message, passing it the name of the 
error, the object that caused the error, and the string constants 
used to format a standard error message. For example, a 
typecheck error reported by the cvn operator would be reported 
as a ‘dps_err_ps’ error code and printed as follows: 

%%[ Error: typecheck; OffendingCommand: cvn ]%% 

The following error codes are common to all Client Library im¬ 
plementations: 

• ‘dps_err_ps’ represents all PostScript language errors 
reported by the interpreter; that is, the errors listed under 
each operator in the PostScript Language Reference 
Manual and PostScript Language Extensions for the Dis¬ 
play PostScript System. See Section B.3 for more infor¬ 
mation about this error code. 

• l dps_err_nameTooLong’ arises if a binary object sequence 
or encoded token has a name whose length exceeds 128 
characters, ‘argl ’ is the PostScript user name; ‘arg2’ is its 
length. 

• l dps_err_invalidContext’ arises if a Client Library routine 
was called with an invalid context. This can happen if the 
client is unaware that the execution context in the inter¬ 
preter has terminated, ‘argl ’ is a context identifier; ‘arg2’ 
is unused. 

• ‘dps_err_resultTagCheck’ occurs when an invalid tag is 
received for a result value. There is one object in the se¬ 
quence. ‘argl’ is a pointer to the binary object sequence; 
‘arg2’ is the length of the binary object sequence. 

• l dps_err_resultTypeCheck’ occurs when the value returned 
is of a type incompatible with the output parameter (for 
example, a string returned to an integer output parameter), 
‘argl’ is a pointer to the binary object (the result with the 
wrong type); ‘arg2’ is unused. 

The remainder of the error codes are specific to the X Window 
System: 
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• l dps_err_invalidAccess’ indicates that a shared context is 
being used improperly. For example, result values were 
erroneously sent to a sharing client other than the creator of 
the context, ‘argl ’ and ‘arg2’ are unused. 

• ‘dps_err_encodingCheck’ indicates that an undefined en¬ 
coding value has been passed to DPSChangeEncoding or 
that the application is trying to change the name encoding 
of a shared context, ‘argl’ is the new name encoding; 
‘arg2’ is the new program encoding. 

• ‘dps_err_closedDisplay’ indicates that the connection to 
the server has been lost, ‘argl ’ is the index number of the 
display; ‘arg2’ is unused. 

• ‘dps_err_deadContext’ indicates that a context has ter¬ 
minated in the interpreter, but the resources assigned to the 
context have not been freed, ‘argl’ is the ‘DPSContext’ 
handle; ‘arg2’ is unused. 


B.3 HANDLING POSTSCRIPT LANGUAGE ERRORS 

The following discussion applies only to the ‘dps_err_ps’ error 
code. This error code represents all possible PostScript operator 
errors. Because the interpreter provides a binary object sequence 
containing detailed information about the error, more options are 
available to the error handler than for other client errors. 

‘argl ’ points to a binary object sequence that describes the error. 
The binary object sequence is a four-element array consisting of 
the name ‘Error’, the name that identifies the specific error, the 
object that was executed when the error occurred, and a boolean 
indicating whether the context expects to be resynchronized. For 
further details of the format of the binary object sequence, see 
PostScript Language Extensions for the Display PostScript 
System. 

The type and length of the array are checked with assertions. The 
body of the array is pointed to by the ‘elements’ variable. Each 
element of the array is derived and placed in a variable. 

DPSDefaultErrorProc raises an exception only if the context ex¬ 
ecuted resyncstart to install resynchandleerror. The 
‘resyncFlag’ variable contains the value of the fourth element of 
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the binary object sequence array, the boolean that indicates 
whether resynchronization is needed. ‘resyncFlag’ will be false 
if the handleerror operator handled the error; it will be true if 
resynchandleerror handled the error. 

If ‘resyncFlag’ is true and the context handling the error is a 
context created by the application, the error handler raises the 
exception by calling RAISE. This call never returns. See Appen¬ 
dix C for a discussion of how RAISE works. 
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C EXCEPTION HANDLING 


This appendix describes a general-purpose exception-handling 
facility. It provides help for a narrowly defined problem area — 
handling PostScript language errors that arise from the con¬ 
ditions listed on page 26. Most application programmers need 
not be concerned with exception handling. These facilities can be 
used in conjunction with PostScript language code and a sophis¬ 
ticated error handler such as DPSDefaultErrorProc to provide a 
certain amount of error recovery capability. Consult the system- 
specific documentation for alternative means of error recovery. 


Note: Avoid using exception handling with the X Window Sys¬ 
tem because lower levels of software, such as Xlib, are not 
prepared to handle exceptions or to have control taken away 
from them. 


An exception is an unexpected condition such as a PostScript 
language error that prevents a procedure from running to normal 
completion. The procedure could simply return, but data struc¬ 
tures might be left in an inconsistent state and returned values 
might be incorrect. Instead of returning, the procedure can raise 
the exception, passing a code that indicates what has happened. 
The exception is intercepted by some caller of the procedure that 
raised the exception (any number of procedure calls deep); ex¬ 
ecution then resumes at the point of interception. As a result, the 
procedure that raised the exception is terminated, as are any in¬ 
tervening procedures between it and the procedure that inter¬ 
cepted the exception, an action which is called “unwinding the 
call stack.” 

The Client Library provides a general-purpose exception¬ 
handling mechanism in dpsexcept.h. This header file provides 
facilities for placing exception handlers in application sub¬ 
routines to respond cleanly to exceptional conditions. 
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Note: Application programs may need to contain the following 
statement: 

#include "dpsexcept.h" 


As an exception propagates up the call stack, each procedure en¬ 
countered can deal with the exception in one of three ways: 

• It ignores the exception, in which case the exception con¬ 
tinues on to the caller of the procedure. 

• It intercepts the exception and handles it, in which case all 
procedure calls below the handler are unwound and dis¬ 
carded. 

• It intercepts, handles, and then reraises the exception, al¬ 
lowing handlers higher in the stack to notice and react to 
the exception. 

The body of a procedure that intercepts exceptions is written as 
follows: 

DURING 
statementl; 
statement; 

HANDLER 

statements 

statements 

END_HANDLER 

The statements between ‘HANDLER’ and ‘ENDJHANDLER’ 
comprise the exception handler for exceptions occurring between 
‘DURING’ and ‘HANDLER’. The procedure body works as fol¬ 
lows: 

• Normally, the statements between ‘DURING’ and 
‘HANDLER’ are executed. 

• If no exception occurs, the statements between ‘HANDLER’ 
and ‘ENDJHANDLER’ are bypassed; execution resumes at 
the statement after ‘ENDJHANDLER’. 

• If an exception is raised while executing the statements be¬ 
tween ‘DURING’ and ‘HANDLER’ (including any proce- 


98 


Client Library Reference Manual / Version of January 23,1990 



dure called from those statements), execution of those 
statements is aborted and control passes to the statements 
between ‘HANDLER’ and ‘ENDJHANDLER’. 


In terms of C syntax, you must treat these macros as if they were 
C code brackets, as follows: 


Macro 

C Equivalent 

‘DURING’ 

{{ 

‘HANDLER’ 

}{ 

‘ENDJHANDLER’ 

}} 


In general, exception-handling macros should either entirely 
enclose a code block (the preferred method — see Example 1 
below) or should be entirely within the block (see Example 2). 

DURING 

while (/* Example 1 7) { 

} 

HANDLER 

ENDJHANDLER 

while (/* Example 2 7) { 

DURING 

HANDLER 

ENDJHANDLER 

} 

When a procedure detects an exceptional condition, it can raise 
an exception by calling RAISE. RAISE takes two arguments. The 
first is an error code (for example, one of the values of 
‘DPSErrorCode’). The second is a pointer, ‘char which may 
point to any kind of data structure, such as a string of ASCII text 
or a binary object sequence. 

The exception handler has two local variables, ‘Exception.Code’ 
and ‘Exception.Message’. When the handler is entered, the first 
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argument that was passed to RAISE get assigned to 
‘Exception.Code’ and the second argument gets assigned to 
‘Exception.Message’. These variables have valid contents only 
between ‘HANDLER’ and ‘END_HANDLER\ 

If the exception handler executes ‘END_HANDLER’ or returns, 
propagation of the exception ceases. However, if the exception 
handler calls RERAISE, the exception — along with 
‘Exception.Code’ and ‘Exception.Message’ — is propagated to 
the next outer dynamically enclosing occurrence of ‘DURING ... 
HANDLER’. 

A procedure may choose not to handle an exception, in which 
case one of its callers must handle it. There are two common 
reasons for wanting to handle exceptions: 

• To deallocate dynamically allocated storage and clean up 
any other local state, then allow the exception to propagate 
further. In this case, the handler should perform its cleanup, 
then call RERAISE. 

• To recover from certain exceptions that might occur, then 
continue normal execution. In this case, the handler should 
compare ‘Exception.Code’ against the set of exceptions it 
can handle. If it can handle the exception, it should per¬ 
form the recovery and execute the statement that follows 
‘ENDJHANDLER’; if not, it should call RERAISE to 
propagate the exception to a higher-level handler. 


Warning: It is illegal to execute a statement between ‘DURING’ 
and ‘HANDLER’ that would transfer control outside of those 
statements. In particular, ‘return’ is illegal: an unspecified error 
will occur. This restriction does not apply to the statements be¬ 
tween ‘HANDLER’ and ‘ENDJHANDLER’. To return from the 
exception handler, call ‘E_RETURN_VOID()’; to perform 
‘return(x)’, call ‘E_RETURN(x)’. 
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C.1 RECOVERING FROM POSTSCRIPT LANGUAGE ERRORS 


The example DPSDefaultErrorProc procedure can be used with 
the PostScript operator resyncstart to recover from PostScript 
language errors. If you use this strategy, an exception can be 
raised by any of the Client Library procedures that write code or 
data to the context: any wrap, any single-operator procedure, 
DPSWritePostScript, and so on. The strategy is as follows: 

• Send the operator resyncstart to the context immediately 
after it is created, resyncstart is a simple read-evaluate- 
print loop enclosed in a stopped clause which, on error, 
executes resynchandleerror. resynchandleerror reports 
PostScript errors back to the client in the form of a binary 
object sequence of a single object: an array of four ele¬ 
ments as described in PostScript Language Extensions for 
the Display PostScript System. The fourth element of the 
binary object sequence, a boolean, is set to true to indicate 
that resynchandleerror is executing. The stopped clause 
itself executes within an outer loop. 

• When a PostScript language error is detected, 
resynchandleerror writes the binary object sequence 
describing the error, flushes the output stream %stdout, 
then reads and discards any data on the input stream 
%stdin until EOF (an end-of-file marker) is received. This 
effectively clears out any pending code and data, and 
makes the context do nothing until the client handles the 
error. 

• The binary object sequence sent by resynchandleerror is 
eventually received by the client and passed to the 
context’s error handler. The error handler formulates a text 
message from the binary object sequence and displays it, 
perhaps by calling the backstop text handler. It then in¬ 
spects the binary object sequence and notices that the 
fourth element of the array, a boolean, is true. This means 
that resynchandleerror is executing and is waiting for the 
client to recover from the error. At this point, the error 
handler may raise an exception by calling RAISE with 
‘dps_err_ps’ and the ‘DPSContext’ pointer, in order to al¬ 
low some exception handler to do specific error recovery. 

• The ‘dps_err_ps’ exception is caught by one of the hand¬ 
lers in the application program. This causes the C stack to 


C.1 RECOVERING FROM POSTSCRIPT LANGUAGE ERRORS 


101 



be unwound, and the handler body to be executed. To 
handle the exception, the application can reset the context 
that reported the error, discarding any waiting code. 

• The handler body calls DPSResetContext, which resets the 
context after an error occurs. This procedure guarantees 
that any buffered I/O is discarded and that the context is 
ready to read and execute more input. Specifically, 
DPSResetContext causes EOF to be put on the context’s 
input stream. 

• We have come full circle now. EOF is received by 
resynchandleerror, which causes it to terminate. The 
outer loop of resyncstart then reopens the context’s input 
stream %stdin, which clears the end-of-file indication and 
resumes execution at the top of the loop. The context is 
now ready to read new code. 

Although the above strategy works well enough for some appli¬ 
cations, it leaves the context and the contents of its private VM 
in an unknown state. For example, the dictionary and operand 
stacks may be cluttered, or free-running forked contexts may 
have been created, or the contents of userdict may have been 
changed. Clearing the state of such a context may be very com¬ 
plicated. 


Note: You may not get PostScript language error exceptions 
when you expect them. Because of various delays related to 
buffering and scheduling, a PostScript language error may be 
reported long after the C procedure responsible for the error has 
returned. This makes it difficult to write an exception handler 
for a given section of code. If this code can cause a PostScript 
language error and will therefore cause DPSDefaultErrorProc to 
raise an exception, you can ensure that you get the exception in a 
timely manner by using synchronization, which is discussed in 
Section 6.4. 
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Warning: In multi-context applications that require error 
recovery, the code to recover from PostScript errors can get quite 
complicated. An exception reporting a PostScript error caused by 
one context can be raised by any call on the Client Library, even 
one on behalf of some other context, including calls made from 
wraps. Although DPSDefaultErrorProc does pass the context 
that caused the error as an argument to RAISE, it is difficult in 
general to deal properly with an exception from one context that 
arises while the application is working with another. 


When the standard handleerror procedure is called to report an 
error, no recovery is possible except to display an error message 
and destroy the context. 


C.2 EXAMPLE EXCEPTION HANDLER 

A typical application might have the following main loop. As¬ 
sume that a context has already been created with 
DPSDefaultErrorProc as its error procedure, and that 
resyncstart has been executed by the context. 
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#include <dpsexcept.h> 

while (/* the user hasn’t quit 7) { 

/* get an input event 7 
event = GetEventFromQueue(); 

/* react to event 7 
DURING 

switch (event) { 
case EVENT_A: 

UserWrapA(context,...); 
break; 

case EVENTJ3: 

UserWrapB(context,...); 
break; 

case EVENT_C: 

ProcThatCallsSeveralWraps(context); 

break; 

/* ... 7 
default:; 

} 

HANDLER 

/* the context’s error proc has already posted an 
error for this exception, so just reset. 

Make sure the context we’re using is the 
one that caused the error! 7 
if (Exception.Code == dps_err_ps) 

DPSResetContext((DPSContext)Exception.Message); 

END_HANDLER 


Most of the calls in the ‘switch’ statement are either direct calls 
to wrapped procedures or indirect calls (that is, calls to 
procedures that make direct calls to wrapped procedures or to the 
Client Library). All of the procedure calls between ‘DURING’ 
and ‘HANDLER’ can potentially raise an exception. The code be¬ 
tween ‘HANDLER’ and ‘END_HANDLER’ is executed only if an 
exception is raised by the code between ‘DURING’ and 
‘HANDLER’. Otherwise, the handler code is skipped. 

Suppose ProcThatCallsSeveralWraps is defined as follows: 
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void ProcThatCallsSeveraiWraps(context) 

DPSContext context; 

{ 

char *s = ProcThatAllocsAString(...); 
int n; 

DURING 

UserWrapCI (context,...); 

UserWrapC2(context, &n); /* user wrap returns a value 7 
DPSPrintf(context, 7%s %d def\n", s, n); /* client lib proc 7 
HANDLER 

if ((DPSContext)Exception. Message == context) 

{ 

I* clean up the allocated string 7 
free(s); 
s = NULL; 

} 

/* let the caller handle resetting the context 7 
RERAISE; 

END_HANDLER 

I* clean up, if we haven’t already 7 
if (s != NULL) free(s); 


This procedure unconditionally allocates storage, then calls 
procedures that may raise an exception. If there were no handler 
here and the exception simply propagated to the main loop, the 
storage allocated for the string would never be reclaimed. The 
solution is to define a handler that frees the storage and then calls 
RERAISE to allow another handler to do the final processing of 
the exception. 
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1 ABOUT THIS DOCUMENT 


This document is your introduction to application development 
using the text and graphics imaging resources of the Display 
PostScript® system. 

This overview for the application programmer describes: 

• The Display PostScript system environment you’ll be inter¬ 
acting with. 

• The Client Library interface you’ll be programming for. 

• The use of the pswrap translator to prepare C-callable 
procedures containing PostScript® language programs. 

• The manuals you’ll need. 


2 ABOUT THE DISPLAY POSTSCRIPT SYSTEM 

The Display PostScript system provides a device-independent 
imaging model for displaying information on a screen. This im¬ 
aging model is fully compatible with the imaging model used in 
PostScript printers. By allowing you to use the PostScript lan¬ 
guage to display text, graphics, and sampled images, it frees you 
from display-specific details such as screen resolution and num¬ 
ber of available colors. 

You can look at the Display PostScript system as part of the 
window system. Your application will use window system fea¬ 
tures for window placement and sizing, menu creation, and event 
handling, while using Display PostScript system features to take 
care of imaging inside the window. 

Display PostScript system components include the Client 
Library, the PostScript interpreter, and the pswrap translator. 
These components are described in the accompanying set of 
manuals. If you are a new PostScript language programmer, 
you’ll also need copies of the PostScript language manuals. See 
Section 6.2 for a discussion of documentation required by appli¬ 
cation developers. 

Figure 1 shows the relationship between your application and the 
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Display PostScript system. The Client Library contains data 
structures and procedures your application will use to send re¬ 
quests to the PostScript interpreter. No matter what operating 
system you’re dealing with, you can send PostScript language 
programs to the interpreter in the same way, using the same pro¬ 
cedure calls. Therefore portability issues are minimized if you’re 
developing an application for more than one environment. 

Figure 1 The Display PostScript System 
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3 APPLICATION BUILDING BLOCKS 

Most of your application will be written in C or another high- 
level languge. You’ll call Client Library procedures to start a 
PostScript execution context, send programs and data to the 
PostScript interpreter, and get results from the the interpreter. 
The Client Library is the application’s primary interface to the 
Display PostScript system. 

In addition, you’ll call wraps — PostScript language procedures 
developed specifically for your application. Wraps, short for 
wrapped procedures, are created by the pswrap translator from 
PostScript language programs written to meet application needs. 
Figure 2 on page 3 shows how an application program is built. 
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4 USING PSWRAP 


Your application will perform calculations, communicate with 
the window system, read and write files, and do other application 
processing in C or another high-level language. It will perform 
imaging tasks by calling wrapped procedures to send PostScript 
language programs to the interpreter. The pswrap translator 
creates these wraps from PostScript language input. 

Figure 2 shows how an application is built of C source code and 
PostScript language code translated into C-callable procedures 
by pswrap. 

Figure 2 Creating a Display PostScript Application 
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Consider a wrap, PSWDisplayText, that places text on the screen 
at a particular x,y coordinate. A call to PSWDisplayText from the 
application program might look something like this: 

PSWDisplayText(72.0,100.0, 'Hello World"); 

The body of the PSWDisplayText procedure, is actually written 
in the PostScript language. It was defined to pswrap as follows: 

defineps PSWDisplayText(float X,Y; char 'text) 

X Y moveto 
(text) show 
endps 

In the wrap definition, the ‘defineps’ and ‘endps’ keywords tell 
pswrap where a given PostScript language program begins and 
ends. The ‘defineps’ statement defines the resulting procedure 
call. The pswrap translator processes this input and produces a C 
language source-code file. When compiled and linked with the 
application, the PSWDisplayText procedure sends a PostScript 
language program to the interpreter (binary-encoded for more ef¬ 
ficient processing), causing the specified text to be displayed. 

To summarize, pswrap takes a PostScript language program as 
input and gives you back a C language program. After you com¬ 
pile the resulting C program and link it into your application, 
calling the wrap will transmit a stream of PostScript language 
binary objects to the interpreter. See the pswrap Reference 
Manual for further information. 


5 THE CLIENT LIBRARY INTERFACE 

The Client Library is a linkable library of compiled C procedures 
that provides an interface between the application and the Dis¬ 
play PostScript system. It creates an environment for handling 
imaging calls to specific Client Library procedures like 
DPSmoveto and custom wraps written for the application. 

The Client Library is tailored by the Display PostScript system 
vendor for your particular operating environment. The Client 
Library Reference Manual describes a generic interface; your 
system vendor may add additional features or slightly modify the 
interface to suit your hardware and software. See your vendor’s 
system-specific documentation for details. 


4 


Perspective for Software Developers / Version of January 23,1990 



6 SUPPORT FOR APPLICATION DEVELOPERS 


Adobe supports application developers by means of the follow¬ 
ing services: 

Adobe Developer Support Line 

A voice mailbox that puts you in touch with 
Adobe’s support services for developers. See 
Section 6.1. 

Technical Literature Catalog 

A free catalog of documentation, available on 
request. 

Documentation 

PostScript language manuals (see Section 6.2), 
developer reference manuals (included with this 
release), and additional technical literature 
defining conventions and standards for 
PostScript language applications (see Section 
6.5). 

Adobe Developer Association 

A membership program for developers, provid¬ 
ing access to technical resources and monthly 
mailings. See Section 6.4. 

Public Access File Server 

Contains technical documents, code examples, 
AFM files, and documentation updates. See Sec¬ 
tion 6.6. 

6.1 THE ADOBE DEVELOPER SUPPORT LINE 

You can call the Adobe Developer Support Line, 

(415) 961-4111, for the following kinds of support: 
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• To receive a free Technical Literature Catalog. 

• To order technical literature. (See Section 6.2 for the toll- 
free number to use when ordering PostScript language 
manuals.) 

• To find out how to become a member of the Adobe 
Developer Association. 

• To request technical assistance (for members of the Adobe 
Developer Association only). 

If you prefer, you can write to us for information. Our mailing 
address is: 


PostScript Developer Support 
Adobe Systems Incorporated 
1585 Charleston Road, P.O. Box 7900 
Mountain View, CA 94039-7900 


6.2 MANUALS FOR APPLICATION DEVELOPERS 

The accompanying set of developer reference manuals contains 
information needed by a programmer developing an application 
for the Display PostScript system. If you’re new to the 
PostScript language, you should first read the following manuals 
(published by Addison-Wesley and available from Adobe by 
calling 1-800-344-8335 or through your technical bookstore): 

PostScript Language Reference Manual 

The standard reference for the PostScript lan¬ 
guage. Describes the PostScript imaging model 
and the concepts and facilities of the PostScript 
interpreter. Documents the PostScript language. 
Required reading. 

PostScript Language Tutorial and Cookbook 

Introduction to the PostScript language in an in¬ 
formal, interactive style. Contains a collection of 
example programs that illustrate the PostScript 
imaging model. 

PostScript Language Program Design 

Guidelines for the advanced developer to use in 
designing and debugging PostScript language 
programs. Printer-oriented, but most of the in¬ 
formation is relevant to writing a Display 
PostScript application. 
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Once you’re up to speed in the PostScript language, read the 
following manuals: 

PostScript Language Extensions for the Display PostScript 
System 

Describes the extensions to the PostScript lan¬ 
guage that were made for the Display PostScript 
system, such as alternative PostScript language 
encodings, multiple execution contexts, user 
paths, window system support, and memory 
management. Introduces important system con¬ 
cepts and documents additional PostScript 
operators. 

Client Library Reference Manual 

Describes the procedural interface to the Display 
PostScript system. Tells how to send programs 
and data to a PostScript execution context, how 
to handle context output, how to create and ter¬ 
minate a context. Contains procedure defini¬ 
tions, programming tips, and a sample applica¬ 
tion program. 

pswrap Reference Manual 

Describes how to define C-callable procedures 
that contain PostScript language programs. Tells 
how to declare input arguments and output to be 
received from the interpreter. Documents the 
pswrap command line options. 

PostScript Language Color Extensions 

Describes color extensions to the PostScript lan¬ 
guage, including multiple color images, color 
halftone screen definitions, color correction, and 
CMYK color specification. 

Because the Display PostScript system has been implemented on 
various system platforms, some of the information required by 
application programmers is necessarily system-specific. There¬ 
fore in addition to the manuals listed above you’ll need to con¬ 
sult the documentation provided by your system software ven¬ 
dor. The following system-specific documentation is available 
from Adobe: 
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X Window System Programmer’s Supplement to the Client 
Library Reference Manual 
Describes information about the Client Library 
interface that is specific to the X Window 

TM 

System , such as context creation and addition¬ 
al error codes. 

6.3 CLASSES FOR APPLICATION DEVELOPERS 

Adobe offers regularly scheduled classes in: 

• Programming in the PostScript language. 

• The Display PostScript environment. 

These classes are held in our East Coast and West Coast facilities 
and in our European office. Classes in Japan are planned for the 
future. 

To receive a schedule of Adobe classes, please call our Training 
Support Line at (415) 961-4949. 

6.4 THE ADOBE DEVELOPER ASSOCIATION 

The Adobe Developer Association is a fee-based membership 
program for active developers using the PostScript page descrip¬ 
tion language or the Display PostScript system to enhance their 
application products. 

You must be a member of the Adobe Developer Association in 
order to take advantage of the following offerings: 

• Technical support. 

• Monthly mailings. 

• Discounts on Adobe Systems application products. 

• Free technical literature. 

You can request a membership application by calling the Adobe 
Developer Support Line. 
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6.5 POSTSCRIPT STANDARDS AND CONVENTIONS 


The following documents define important conventions and stan¬ 
dards that promote compatibility, efficiency, and quality for all 
PostScript language applications. These documents are available 
through the Adobe Developer Support Line or the public access 
file server. 

Document Structuring Conventions Specification 

Replaces Appendix C of the PostScript Lan¬ 
guage Reference Manual (Version 1.0 of the 
PostScript language document structuring 
conventions). These conventions are important 
for generating page description files suitable for 
print spoolers, previewer applications, and post¬ 
processors, as well as PostScript printers. 

Encapsulated PostScript File Format (EPSF) 

Specifies the document format required for ex¬ 
change of PostScript language files. This 
specification suggests a standard for importing 
PostScript language files in all environments. 
Applications that support EPSF can exchange 
graphical output with each other. 

PostScript Printer Description Files Specification 

Describes the Adobe Systems PostScript Printer 
Description (PPD) files and their usage. PPD 
files are text files in a format that can be read by 
people and parsed by computers. They are useful 
for determining and using the special features 
available on printers with PostScript interpreters. 

Adobe Font Metric Files Specification 

Describes the Adobe standard interchange for¬ 
mat for communicating font metric information 
to people and programs. 
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6.6 THE PUBLIC ACCESS FILE SERVER 


If you have access to Internet or UUCP electronic mail, you can 
use Adobe’s public access file server to obtain the following in¬ 
formation: 

• Code examples. 

• AFM files. 

• Documentation updates. 

• Conventions and standards documents listed in Section 6.5. 

The public access file server is a mail-response program. That is, 
you send it a request by electronic mail and it mails back a 
response. (The “Subject:” line is treated as part of the message 
by the file server.) 

To send mail to the file server, use one of the following ad¬ 
dresses: 

Internet ps-file-server@adobe.com 

UUCP ...!decwrl!adobe!ps-file-server 

To receive a quick summary of file server commands, send the 
following message: 

help 

To receive detailed information on how to use the file server, 
send the following message: 

send Documents long.help 
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A CHANGES SINCE LAST PUBLICATION OF THIS DOCUMENT 


The changes to Perspective for Software Developers from the 
document dated October 25, 1989, are noted in the paragraphs 
below. 

A section has been added to describe support services available 
from Adobe Systems, including the Adobe Developer Support 
Line, the Technical Literature Catalog, the Adobe Developer As¬ 
sociation, and the public access file server. 

The changes to Perspective for Software Developers from the 
document dated October 10, 1988, are noted in the paragraphs 
below. 

The manual has been rewritten and reorganized. A list of sug¬ 
gested reading for software developers has been added. 
Diagrams have been provided to illustrate the following: 

• The relationship of the Client Library and the PostScript 
interpreter to application and system software. 

• The creation of a Display PostScript system application. 
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1 ABOUT THIS MANUAL 


This manual is the programmer’s reference manual for the 
pswrap translator. It tells you how to use pswrap to create C- 
callable procedures that contain PostScript® language code. 

Section 2 introduces the pswrap translator. 

Section 3 tells you how to run pswrap and documents the options 
in the pswrap command line. 

Section 4 tells you how to write wrap definitions for pswrap. 

Section 5 tells you how to declare input arguments. 

Section 6 tells you how to declare output arguments. 

Appendix A lists error messages from the pswrap translator. 

Appendix B describes the syntax used in wrap definitions. 

Appendix C lists changes to the manual since the previous 
version. 

This manual does not provide information on the PostScript lan¬ 
guage, the Display PostScript® system, or the Client Library (the 
programming interface to the Display PostScript system). For 
more information regarding these topics, see the following 
manuals: 

• PostScript Language Reference Manual 

• PostScript Language Extensions for the Display PostScript 
System 

• PostScript Language Color Extensions 

• Client Library Reference Manual 


2 ABOUT PSWRAP 

The pswrap translator provides a natural way for an application 
developer or toolkit implementor to compose a package of C- 
callable procedures that send PostScript language code to the 
PostScript interpreter. These C-callable procedures are known as 
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wrapped procedures or wraps. (A wrap is a procedure that con¬ 
sists of a C declaration with a PostScript language body. A wrap 
body is the PostScript language program fragment in a wrap.) 

Here’s how pswrap fits into the Display PostScript system: 

• You write the PostScript language programs required by 
your application, using the pswrap syntax described in this 
manual to define a C-callable procedure and specify input 
and output arguments. 

• You run pswrap to translate these PostScript language 
programs into wrapped procedures. 

• You compile and link these wraps with the application 
program. 

• When a wrap is called by the application, it sends encoded 
PostScript language to the PostScript interpreter and 
receives the values returned by the interpreter. 

A pswrap source file associates PostScript language code with 
declarations of C procedures; pswrap writes C source code for 
the declared procedures, in effect wrapping C code around the 
PostScript language code. Wrapped procedures can take input 
and output arguments: 

• Input arguments are values a wrap sends to the PostScript 
interpreter as PostScript objects. 

• Output arguments are pointers to variables where the wrap 
stores values returned by the PostScript interpreter. 

Wraps are the most efficient way for an application to commu¬ 
nicate with the PostScript interpreter. 


3 USING PSWRAP 

The form of the pswrap command line (UNIX- and C-specific) 
is: 

pswrap [-apr] [-o outputCfile] [-h outputHfile] [-s maxstring] [inputFile] 
where square brackets [ ] indicate optional items. 
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3.1 COMMAND-LINE OPTIONS 


The pswrap command-line options are described below. 


inputFile A file that contains one or more wrap defini¬ 
tions. pswrap transforms the definitions in 
inputFile into C procedure definitions. If no in¬ 
put file is specified, the standard input (which 
can be redirected from a file or pipe) is used. 
The input file can include text other than proce¬ 
dure definitions, pswrap converts procedure 
definitions to C procedures and passes the other 
text through unchanged; therefore, it is possible 
to intersperse C-language source code with wrap 
definitions in the input file. 


Note: Although C code is allowed in a pswrap input file, it is 
not allowed within a wrap body. In particular, C ‘#define’ mac¬ 
ros cannot be used inside a wrap. 


-a Generates ANSI C procedure prototypes for pro¬ 

cedure declarations in outputCfile and, option¬ 
ally, outputHfile. (See the -h option.) The -a op¬ 
tion allows compilers that recognize the ANSI C 
Standard to do more complete typechecking of 
parameters. To save space, the -a option also 
causes pswrap to generate ‘const’ declarations. 


Note: ANSI C procedure prototype syntax is not recognized by 
most non-ANSI C compilers, including many compilers based 
on the Portable C Compiler. Use the -a option only in 
conjunction with a compiler that conforms to the ANSI C Stan¬ 
dard. 


•h outputHFile Generates a header file that contains ‘extern’ 
declarations for nonstatic wraps. This file may 
be used in ‘#include’ statements in modules that 
use wraps. If the -a option is specified, the 
declarations in the header file are ANSI C proce¬ 
dure prototypes. If the -h option is omitted, a 
header file is not produced. 
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■o outputCFile Specifies the file to which the generated wraps 
and passed-through text are written. If omitted, 
the standard output is used. If the -a option is 
also specified, the procedure declarations 
generated by pswrap are in ANSI C procedure 
prototype syntax. 

•p Specifies that strings passed by wraps are 

padded so that the next field begins on a long 
word (four-byte) boundary. 

■r Generates reentrant code for wraps that are 

shared by more than one process (as in shared 
libraries). Since the -r options causes pswrap to 
generate extra code, use it only when necessary. 

■s maxstring Sets the maximum allowable length of a 

PostScript string object or PostScript hex string 
object in the wrap body input. A syntax error 
will be reported if a string is not terminated with 
*)’ or V within maxstring characters, maxstring 
cannot be set lower than 80. The default is 200. 


3.2 ‘#LINE’ DIRECTIVES 

Since the C source code generated for wrapped procedures 
usually contains more lines than the input wrap body does, 
pswrap inserts ‘#line’ directives into the output wrap. These 
directives record input line numbers in the output wrap source 
file so that a source-code debugger can display them. Since a 
debugger displays C source code, not the PostScript language 
code in the wrap body, pswrap inserts #line directives for both 
the inputFile and the outputCfile. 


Note: Unless both the input and output files are named on the 
command line, the ‘#line’ directives will be incomplete; in the 
latter case, they will lack the name of the C source file pswrap 
produces. Use of the standard input and standard output streams 
is discouraged for this reason. 


pswrap writes diagnostic output to the standard error if there are 
errors in the command line or in the input. If pswrap encounters 
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errors during processing, it reports the error and exits with a non¬ 
zero termination status. 


4 WRITING A WRAP 

Here is a sample wrap definition. It declares the PSWGrayCircle 
procedure, which creates a solid gray circle with a radius of 5.0 
centered at (10.0,10.0): 

Wrap definition: 

defineps PSWGrayCircle() 
newpath 

10.0 10.0 5.0 0.0 360.0 arc 
closepath 
0.5 setgray 
fill 
endps 

Procedure call: 

PSWGrayCircle(); 

PostScript language code equivalent: 
newpath 

10.010.0 5.0 0.0 360.0 arc 

closepath 

0.5 setgray 

fill 

The rules for defining a wrapped procedure are given in the next 
section. 


4.1 THE WRAP DEFINITION 

Each wrap definition consists of four parts: 

‘defineps’ Begins the definition; must appear at the begin¬ 
ning of a line, without any preceding spaces or 
tabs. 

Declaration of the C-callable procedure 

The name of the procedure followed by a list in 
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parentheses of the arguments it takes. The argu¬ 
ments are optional; the parentheses are required 
even for a procedure without arguments. (Note 
that wraps do not return values; they are 
declared ‘void’.) 

Wrap body PostScript language program fragment. This 
fragment is sent to the PostScript interpreter. It 
includes a series of PostScript operators and 
operands separated by spaces, tabs, and newline 
characters. 

‘endps’ Ends the definition. Like ‘defineps’, ‘endps’ 

must appear at the very beginning of a line. 

By default, wrap definitions introduce external (that is, global) 
names that can be used outside the file in which the definition 
appears. To introduce private (local) procedures, declare the 
wrapped procedure as static. For example, the PSWGrayCircle 
wrap shown above can be made static by substituting the follow¬ 
ing statement for the first line: 

defineps static PSWGrayCircie() 


Note: It is helpful for the application to use a naming conven¬ 
tion for wraps that identifies them as such; for example, 
PSWDrawBox, PSWShowTitle, PSWDrawSlider, and so on. 


4.2 COMMENTS 

C comments can appear anywhere outside a wrap definition. 
PostScript language comments can appear anywhere after the 
procedure is declared and before the definition ends, pswrap 
strips PostScript language comments from the wrap body. Com¬ 
ments cannot appear within PostScript string objects: 

/‘This is a C comment*/ 
defineps PSWNoComment() 

(/‘This is not a comment*/)show 
(%Nor is this.)length 
%This is a PS comment 
endps 
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Wraps cannot be used to send PostScript language comments 
that contain structural information {%% and %!). Use another 
Client Library facility such as DPSWriteData for this purpose. 


4.3 THE WRAP BODY 

pswrap accepts any valid PostScript language code as specified 
in the PostScript Language Reference Manual, PostScript Lan¬ 
guage Extensions for the Display PostScript System, and 
PostScript Language Color Extensions. If the PostScript lan¬ 
guage code in a wrap body includes any of the following sym¬ 
bols, the opening and closing marks must balance. 

‘{}’ Braces (to delimit a procedure) 

‘[ ]’ Square brackets (to define an array) 

‘O’ Parentheses (to enclose a string) 

‘< >’ Angle brackets (to mark a hexdecimal string) 

Parentheses within a string body must balance or be quoted with 
‘V according to standard PostScript language syntax. 


Note: pswrap does not check a wrap definition for valid or sen¬ 
sible PostScript language code. 


pswrap attempts to wrap whatever it encounters. Everything be¬ 
tween the closing parenthesis of the procedure declaration and 
the end of the wrap definition is assumed to be an element of the 
PostScript language unless it is part of a comment or matches 
one of the wrap arguments. 


Note: pswrap does not support the // PostScript language syntax 
for immediately evaluated names. See the PostScript Language 
Reference Manual for more information about immediately 
evaluated names. 
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4.4 ARGUMENTS 


Argument names in the procedure header are declared using C 
types. For instance, the following example declares two vari¬ 
ables, ‘x’ and ‘y’> of type ‘long int’. 

defineps PSWMyFunc(long int x,y) 

There can be any number of input and output arguments. Input 
arguments must be listed before output arguments in the wrap 
header. Precede the output arguments, if any, with a vertical bar 
T. Separate arguments of the same type with a comma. Separate 
arguments of differing types with a semicolon. A semicolon is 
optional before a vertical bar or a right parenthesis; the two ex¬ 
amples below are equivalent: 

defineps PSWNewFunc(float x,y; int a I int *i) 
defineps PSWNewFunc(float x,y; int a; I int *i;) 

4.5 INPUT ARGUMENTS 

Input arguments describe values that the wrap converts to en¬ 
coded PostScript objects at run time. When an element within 
the wrap body matches an input argument, the value that was 
passed to the wrap replaces the element in the wrap body. Input 
arguments represent placeholders for values in the wrap body. 
They are not PostScript language variables (names). Think of 
them as macro definitions that are substituted at run time. 

For example, the PSWGrayCircle procedure defined on page 5 
can be made more useful by providing input arguments for the 
radius and center coordinates: 
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Wrap definition: 


defineps PSWGrayCircle(float x,y, radius) 
newpath 

x y radius 0.0 360.0 arc 
closepath 
0.5 setgray 
fill 
endps 

Procedure call: 

PSWGrayCircle(25.4,17.7, 40.0); 
PostScript language code equivalent : 
newpath 

25.4 17.7 40.0 0.0 360.0 arc 

closepath 

0.5 setgray 

fill 


The value of input argument ‘x’ replaces every occurrence of ‘x’ 
in the wrap body. This version of PSWGrayCircle draws a circle 
of a specified size at a specified location. 


4.6 OUTPUT ARGUMENTS 

Output arguments describe values that PostScript operators 
return. For example, the standard PostScript operator 
currentgray returns the gray-level setting in the current graphics 
state. PostScript operators return values by placing them on the 
top of the operand stack. To return the value to the application, 
place the name of the output argument in the wrap body at a time 
when the desired value is on the top of the operand stack. For 
example, the following wrap gets the value returned by 
currentgray: 
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Wrap definition: 


defineps PSWGetGray( I float ‘level) 
currentgray level 
endps 

Procedure call: 

float aLevel; 

PSWGetGray(&aLevel); 

PostScript language code equivalent : 

currentgray 

% Pop current gray level off operand stack 
% and store in aLevel. 1 

When an element within a wrap body matches an output argu¬ 
ment in this way, pswrap replaces the output argument with code 
that returns the top object on the operand stack. For every output 
argument, the wrap will perform the following operations: 

• Pop an object off the operand stack. 

• Send it to the application. 

• Convert it to the correct C data type. 

• Store it at the place designated by the output argument. 

Each output argument must be declared as a pointer to the loca¬ 
tion where the procedure stores the returned value. To get a ‘long 
int’ back from a /wvvrap-generated procedure, declare the output 
argument as ‘long int as in the following example: 


' See the “Runtime Support” section of the Client Library Reference Manual 
for a discussion of how pswrap uses the printobject operator to return results. 
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Wrap definition: 

defineps PSWCountExecStack( I long int *n) 
countexecstack n 
endps 

Procedure call: 

long int aNumber; 

PSWCountExecStack(&aNumber); 

PostScript language code equivalent: 

countexecstack 

% Pop count of objects on exec stack 
% and return in aNumber. 

To receive information back from the PostScript interpreter, use 
only the syntax for output arguments described here. Do not use 
operators that write to the standard output (such as =, ==, print, 
or pstack). These operators send ASCII strings to the application 
that pswrap- generated procedures cannot handle. 
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Warning: For an operator that returns results, the operator 
description shows the order in which results are placed on the 
operand stack, reading from left to right. (See the “Operators” 
chapters of the PostScript Language Reference Manual and 
PostScript Language Extensions for the Display PostScript 
System.) When you specify a result value in a wrap body, the 
result is taken from the top of the operand stack. Therefore the 
order in which wrap results are stated must be the reverse of their 
order in the operator description. 

For instance, the PostScript operator description for 
currentpoint returns two values, jr and y: 

- currentpoint x y 

The corresponding wrap definition must be written: 

defineps PSWcurrentpoint (I float *x, *y) 

currentpoint y x % Note: y before x. 
endps 


Sections 5 and 6 discuss the details of input and output argu¬ 
ments, respectively. 


5 DECLARING INPUT ARGUMENTS 

This section defines the data types allowed as input arguments in 
a wrap. In the following list, square brackets indicate optional 
elements: 


12 


pswrap Reference Manual / Version of August 30,1990 



• ‘DPSContext’. If the wrap specifies a context, it must ap¬ 
pear as the first input argument. (‘DPSContext’ is a handle 
to the context record; see the Client Library Reference 
Manual for more information.) 


• One of the following pswrap data types (equivalent to C 
data types except for ‘boolean’, ‘userobject’, and 
‘numstring’, which are special to pswrap ): 


‘boolean’ 

‘int’ 

‘short [ int ]’ 
‘long [ int ]’ 
‘float’ 

‘numstring’ 


‘userobject’ 

‘unsigned [int]’ 
‘unsigned short [ int ]’ 
‘unsigned long [ int]’ 
‘double’ 


• An array of a pswrap data type 

• A character string (‘char *’ or ‘unsigned char *’) 

• A character array (‘char [ ]’ or ‘unsigned char [ ]’) (The 
square brackets are part of C syntax.) 

A string (‘char *’) passed as input may not be more than 65,535 
characters. An array may not contain more than 65,535 elements. 


5.1 SENDING BOOLEAN VALUES 

If an input argument is declared as ‘boolean’, the wrap expects 
to be passed a variable of type ‘int’. If the variable has a value of 
zero, it is translated to a PostScript boolean object with the value 
false. Otherwise it is translated to a PostScript boolean object 
with the value true. 


5.2 SENDING USER OBJECT VALUES 

Input parameters declared as type ‘userobject’ should be passed 
as type ‘long int’. The value of a ‘userobject’ argument is an 
index into the UserObjects array. See PostScript Language Ex¬ 
tensions for the Display PostScript System for a description of 
user objects. 

When pswrap encounters an argument of type userobject, it will 
generate PostScript language code to obtain the object associated 
with the index. For example: 
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Wrap definition: 


defineps PSWAccessUserObject(userobject x) 
x 

endps 

Procedure call: 

long int allserObject; 

/* assume aUserObject = 6 7 
PSWAccessllserObject(aUserObject); 

PostScript language code equivalent: 

6 execuserobject 

If the object is executable, it will be executed; if it’s not ex¬ 
ecutable, it will be pushed on the operand stack. 

If you want to pass the index of a user object without having it 
translated by pswrap as described above, declare the argument to 
be of type ‘long int’ rather than type ‘userobject’. Here is an 
example of a wrap that defines a user object: 

Wrap definition: 

defineps PSWDefUserObject(long int d) 
d 10 diet defineuserobject 
endps 

Procedure call: 

long int an Index; 

I* assume anlndex = 12 */ 

PSWDefUserObject(anlndex); 

PostScript language code equivalent: 

12 10 diet defineuserobject 
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5.3 SENDING CHARACTERS 


An input argument composed of characters is treated as a 
PostScript name object or string object. The argument can be 
declared as a character string or as a character array. 

pswrap expects arguments that are passed to it as character 
strings (‘char *’ or ‘unsigned char *’) to be null terminated 
(‘\0’). Character arrays are not null terminated. The number of 
elements in the array must be specified as an integer constant or 
as an input argument of type ‘int’. In either case, the integer 
value must be positive. See Section 5.5 for an example of this 
rule. 

5.3.1 Text Arguments 

An input argument declared as a character string or character 
array is converted to a single PostScript name object or string 
object. Such an argument is referred to as a text argument. 

The PostScript interpreter does not process the characters of text 
arguments. It assumes that any escape sequences (‘\n\ ‘\t\ and 
so on) have been processed before the wrap is called. 

To make pswrap treat a text argument as a PostScript literal 
name object, precede it with a slash, as in the PSWReadyFont 
wrap definition below. (Only names and text arguments can be 
preceded by a slash.) 
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Wrap definition: 


defineps PSWReadyFont( char *fontname; int size) 
/fontname size selectfont 
endps 

Procedure call: 

PSWReadyFont("Sonata“, 6); 

PostScript language code equivalent : 

/Sonata 6 selectfont 

To make pswrap treat a text argument as a PostScript string ob¬ 
ject, enclose it within parentheses. The PSWPutString wrap defi¬ 
nition below shows a text argument, ‘(str)’: 

Wrap definition: 

defineps PSWPutString(char *str; float x, y) 
x y moveto 
(str) show 
endps 

Procedure call: 

PSWPutString("Hello World", 72.0, 72.0); 

PostScript language code equivalent: 

72.0 72.0 moveto 
(Hello World) show 


Note: Text arguments are recognized within parentheses only if 
they appear alone, without any surrounding whitespace or addi¬ 
tional elements. In the following wrap definition, only the first 
string is replaced with the value of the text argument. The 
second and third strings are sent unchanged to the interpreter. 

defineps PSWThreeStrings(char *str) 

(str) ( str ) (a str) 
endps 
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If a text argument is not marked by either a slash or parentheses, 
pswrap treats it as an executable PostScript name object. In the 
following example, ‘mydict’ is treated as executable: 

Wrap definition: 

defineps PSWDoProcedure(char ‘mydict) 
mydict /procedure get exec 
endps 

Procedure call: 

PSWDoProcedureflexicon”); 

PostScript language code equivalent: 
lexicon /procedure get exec 

5.4 SENDING NUMBERS 

An input argument declared as one of the ‘int’ types is converted 
to a 32-bit PostScript integer object before it is sent to the inter¬ 
preter. A ‘float’ or ‘double’ input argument is converted to a 32- 
bit PostScript real object. These conversions follow the usual C 
conversion rules. 2 


Note: Since the PostScript language does not support unsigned 
integers, unsigned integer input arguments are converted to 
signed integers in the body of the wrap. 


5.5 SENDING ARRAYS OF NUMBERS OR BOOLEANS 

Each element in the wrap body that names an input array argu¬ 
ment represents a PostScript literal array object that has the same 
element values. In the PSWSetMyMatrix wrap definition below, 
the current transformation matrix is set using an array of six 
floating-point values: 


2 See The C Programming Language, R. W. Kemighan and D. M. Ritchie 
(Englewood Cliffs, NJ: Prentice-Hall, 1978) or C: A Reference Manual, 
S. P. Harbison and G. L. Steele, Jr. (Englewood Cliffs, NJ: Prentice-Hall, 
1984). 
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Wrap definition: 


defineps PSWSetMyMatrix (float mtx[6]) 
mtx setmatrix 
endps 

Procedure call: 

static float anArray[] = {1.0,0.0,0.0, -1.0, 0.0,0.0}; 

PS WSetMyMatrix(an Array); 

PostScript language code equivalent : 

[1.0 0.0 0.0 -1.0 0.0 0.0] setmatrix 

The PSWDefineA wrap below sends an array of variable length 
to the PostScript interpreter: 

Wrap definition: 

defineps PSWDefineA (int data[x]; int x) 

/A data def 
endps 

Procedure call: 

static intd1[] = {1,2, 3}; 
static int d2[] = {4,5}; 

PSWDefineA(d1,3); 

PSWDefineA(d2,2); 

PostScript language code equivalent: 

/A [1 2 3] def 
/A [4 5] def 

5.6 SENDING A SERIES OF NUMERIC OR BOOLEAN VALUES 

Occasionally, it is useful to group several numeric or boolean 
values into a C array and pass the array to a wrap that will send 
the individual elements of the array to the PostScript interpreter, 
as in the following example: 
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Wrap definition: 

defineps PSWGrayCircle(float nums[3], gray) 
newpath 

\nums[0] \nums[1] \nums[2] 0.0 360.0 arc 
closepath 
gray setgray 
fill 
endps 

Procedure call: 

static float xyRadius = {40.0, 200.0, 55.0}; 

PSWGrayCircle(xyRadius, .75); 

PostScript language code equivalent: 

newpath 

40.0 200.0 55.0 0.0 360.0 arc 

closepath 

.75 setgray 

fill 


In the example above, ‘\nums[ / ]’ identifies an element of an 
input array in the wrap body, where ‘nums’ is the name of an 
input boolean array or numeric array argument, i is a non¬ 
negative integer literal, and no whitespace is allowed between ‘V 
and ‘]\ 

5.6.1 Specifying the Size of an Input Array 

As the foregoing examples illustrate, you can specify the size of 
an input array in two ways: 

• Give an integer constant as the size when you define the 
procedure, as in the PSWGrayCircle wrap definition. 

• Give an input argument that evaluates to an integer at run 
time as the size, as in the PSWDefmeA wrap definition on 
page 18. 

In either case, the size of the array must be a positive integer 
with a value not greater than 65,535. 
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5.7 SENDING ENCODED NUMBER STRINGS 

A number sequence in the PostScript language may be 
represented either as an ordinary PostScript array object whose 
elements are to be used successively or as an encoded number 
string. Encoded number strings are described in the ‘Alternative 
Language Encodings’ section of PostScript Language Extensions 
for the Display PostScript System. 

The encoded number string format efficiently passes sequences 
of numbers, such as coordinates, to PostScript operators that take 
arrays of operands (xyshow and rectfill, among others). In this 
form, the arrays take up less space in PostScript VM. In addition, 
the operator that consumes them executes faster because the data 
in an encoded number string, unlike a PostScript array object, 
does not have to be scanned by the PostScript scanner. 

To simplify passing encoded number strings in a wrap, pswrap 
syntax provides the ‘numstring’ data type, ‘numstring’ lets you 
pass PostScript operands as numeric elements in a normal C 
array. The pswrap translator generates code that produces the 
encoded number string corresponding to this C array. 


Note: ‘numstring’ may be used only for input. It is invalid as 
an output parameter in a wrap definition. 
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The syntax of the ‘numstring’ data type is as follows; optional 
items are in curly brackets: 

{modifier} numstring variablename[arraysize] {:scale; sizetype arraysize; scaletype scale}; 

The modifier is one of the following: 


Modifier 

C array 

Encoded number string equivalent 

‘int’ 

int 

fixed (native integer size) — the default 

‘long’ 

long int 

fixed (32-bit fixed-point number) 

‘short’ 

short int 

fixed (16-bit fixed-point number) 

‘float’ 

float 

real (32-bit floating-point number) 


Here are some examples of wrap definitions that pass an encoded 
number string. In these wraps, ‘c’ is a constant and ‘n’ and ‘s’ 
are integer variables representing the number of elements and the 
scale, respectively. Scale refers to the number of digits to the 
right of the decimal point. Scale applies only to fixed-point num¬ 
bers; if not specified, it defaults to zero. 
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defineps PSWNumsI (numstring a[5];) 

% Array of 5 elements of default format 
% (native integer size, zero scale). 

defineps PSWNums2(float numstring a[c];) 

% Array size is constant. 

defineps PSWNums3(float numstring a[n]; int n;) 

% Array size is variable. 

defineps PSWNums4(int numstring a[n]:s; int n, s;) 
% Native integer size, non-zero scale. 

defineps PSWNums5(long numstring a[n]:s; int n, s;) 
% 32-bit fixed point, non-zero scale. 

defineps PSWNums6(short numstring a[n]:c; int n;) 
% 16-bit fixed point, non-zero scale. 
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PSWXShowChars is an example of a wrap that uses the 
‘numstring’ data type to pass an array of user-defined widths to 
the xshow operator. 

Wrap definition: 

defineps PSWXShowChars(char str[4]; long numstring widths[4]:0) 
/Times-Roman 30 selectfont 
100 100 moveto 
str widths xshow 
endps 

Procedure call: 

char str[4] = "test"; 

long widths[4] = {7,10, 9, 7}; 

PSWXShowChars(str, widths); 

PostScript language code equivalent : 

/Times-Roman 30 selectfont 
/str (test) def 

/widths <95800400070000000A0000000900000007000000> def 
% encoded number string, hex format, 

% preceded by 4-byte generated header 

100 100 moveto 
str widths xshow 


5.8 SPECIFYING THE CONTEXT 

Every wrap communicates with a PostScript execution context. 
The current context is normally used as the default. The Client 
Library provides operations for setting and getting the current 
context for each application. To override the default, declare the 
first argument as type ‘DPSContext’ and pass the appropriate 
context as the first parameter whenever the application calls the 
wrap. Here is an example of a wrap definition that explicitly 
declares a context: 
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Wrap definition: 


defineps PSWGetGray(DPSContext c I float *level) 
currentgray level 
endps 

Procedure call: 

DPSContext myContext; 
float aLevel; 

PSWGetGray(myContext, &aLevel); 

PostScript language code equivalent: 
currentgray 

% Pop current gray level off operand stack 
% and store in aLevel 


Warning: Do not refer to the name of the context in the wrap 
body. 


6 DECLARING OUTPUT ARGUMENTS 

To receive information back from the PostScript interpreter, the 
output arguments of a wrap must refer to locations where the 
information can be stored. An output argument can be declared 
as one of the following: 

• A pointer to one of the pswrap data types listed on page 13, 
except for ‘userobject’. 

• An array of one of these types. 

• A character string (‘char *’ or ‘unsigned char *’). 

• A character array (‘char [ ]’ or ‘unsigned char [ ]’). 

If an output argument is declared as a pointer or character string, 
the procedure writes the returned value at the location pointed to. 

For an output argument declared as a pointer, previous return 
values are overwritten if the output argument is encountered 
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more than once in executing the wrap body. For an output argu¬ 
ment declared as a character string (‘char *’), the value is stored 
only the first time it is encountered. 

If an output argument is declared as an array of one of the 
pswrap data types (see page 13 for a list) or as a character array, 
the wrap fills the slots in the array (see Section 6.3). 


Note: Whenever an array output argument is encountered in the 
wrap body, the values on the PostScript operand stack are placed 
in the array in the order in which they would be popped off the 
stack. When no empty array elements remain, no further storing 
of output in the array is done. No error is reported if elements 
are returned to an array that is full. 


You can specify output arguments in the ‘defineps’ statement in 
any order that is convenient. The order of the output arguments 
has no effect on the execution of the PostScript language code in 
the wrap body. 

pswrap does not check whether the wrap definition provides 
return values for all output arguments, nor does it perform type 
checking for declared output arguments. 

6.1 RECEIVING NUMBERS 

PostScript integer objects and real objects are 32 bits long. When 
returned, these values are assigned to the variable provided by 
the output argument. On a system where the size of an ‘inf or 
‘float’ is 32 bits, pass a pointer to an ‘inf as the output argument 
for a PostScript integer object; pass a pointer to a ‘float’ as the 
output argument for a PostScript real object: 

defineps PSWMyWrap (I float *f; int *i) 

A PostScript integer object or real object can be returned as a 
‘float’ or ‘double’. Other type mismatches cause a typecheck er¬ 
ror (for example, attempting to return a PostScript real object as 
an ‘int’). 
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6.2 RECEIVING BOOLEAN VALUES 

A procedure can declare a pointer to a ‘boolean’ as an output 
argument: 

Wrap definition: 

defineps PSWKnown(char *Dict, *x I boolean *ans) 

Diet /x known ans 
endps 

Procedure call: 

int found; 

PSWKnownfstatusdict", "duplex”, &found); 

PostScript language code equivalent: 
statusdict /duplex known found 

This wrap expects to be passed the address of a variable of type 
‘int’ as its output argument. If the PostScript interpreter returns 
the value true, the wrap places a value of 1 in the variable 
referenced by the output argument. If the interpreter returns the 
value false, the wrap places a value of zero in the variable. 

6.3 RECEIVING A SERIES OF OUTPUT VALUES 

To receive a series of output values as an array, declare an array 
output argument; then write a wrap body in the PostScript lan¬ 
guage to compute and return its elements, one or more elements 
at a time. The example below declares a wrap that returns the 
256 font widths for a given font name at a given font size: 
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Wrap definition: 

defineps PSWGetWidths(char *fn; int size I float wide[256]) 
/fn size selectfont 
0 1 255 { 

(X) dup 0 4-1 roll put 
stringwidth pop wide 

} for 
endps 

Procedure call: 

float widths[256]; 

PSWGetWidthsfSerifa", 12, widths); 

PostScript language code equivalent : 

/Serifa 12 selectfont 
0 1 255 { 

(X) dup 0 4-1 roll put 
stringwidth pop 

% Pop width for this character and insert width 
% into widths array at current element; 

% point to next element. 

} for 

In the above example, the loop counter is used to assign succes¬ 
sive ASCII values to the scratch string ‘(X)’. The stringwidth 
operator then places both the width and height of the string on 
the PostScript operand stack. (Here it operates on a string just 
one character long.) The pop operator removes the height from 
the stack, leaving the width at the top. The occurrence of the 
output argument ‘wide’ in this position triggers the width to be 
popped from the stack, returned to the application, and inserted 
into the output array at the current element. The next element 
then becomes the current element. 

The for loop (the procedure enclosed in braces followed by for) 
repeats these operations for each character in the font, beginning 
with the 0th and ending with 255th element of the font array. 

6.3.1 Receiving a Series of Array Elements 

A PostScript array object can contain a series of elements to be 
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stored in an output array. The output array is filled in, one ele¬ 
ment at a time, until it’s full. Therefore the PSWTest wrap 
defined below will return ‘{1,2, 3, 4, 5, 6}’: 

defineps PSWTest(l int Array[6]) 

[1 2 3] Array 
[4 5 6] Array 
endps 

The PSWTestMore wrap defined below will return ‘{1,2, 3, 4}’: 

defineps PSWTestMore(l int Array[4]) 

[12 3] Array 
[4 5 6] Array 
endps 

6.3.2 Specifying the Size of an Output Array 

The size of an output array is specified in the same manner as the 
size of an input array. Use a constant in the wrap definition or an 
input argument that evaluates to an integer at run time. If more 
elements are returned than fit in the output array, the additional 
elements are discarded. 

6.4 RECEIVING CHARACTERS 

To receive characters back from the PostScript interpreter, 
declare the output argument either as a character string or as a 
character array. 

If the argument is declared as a character string, the wrap copies 
the returned string to the location indicated. Be careful to 
provide enough space for the maximum number of characters 
that might be returned, including the null character (‘\0’) that 
terminates the string. Only the first string encountered will be 
returned. For example, in the PSWStrings procedure defined 
below, the string ‘123’ will be returned: 

defineps PSWStrings(l char *str) 

(123) str 
(456) str 
endps 
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Character arrays, on the other hand, are treated just like arrays of 
numbers. In the PSWStrings2 procedure, the value returned for 
‘str’will be‘123456’: 

defineps PSWStrings2(l char str[6]) 

(123) str 
(456) str 
endps 

If the argument is declared as a character array (for example, 
‘char s’[nM/n]), the procedure copies up to num characters of the 
returned string into the array. Additional characters are dis¬ 
carded. The string is not null terminated. 

6.5 COMMUNICATION AND SYNCHRONIZATION 

The PostScript interpreter can run as a separate process from the 
application; it can even run on a separate machine. When the 
application and interpreter processes are separated, the applica¬ 
tion programmer must take communication into account. This 
section alerts you to communication and synchronization issues. 

A wrap that has no output arguments returns as soon as the wrap 
body is transferred to the client/server communication channel. 
In this case, the communication channel is not necessarily 
flushed. Since the wrap body is not executed by the PostScript 
interpreter until the communication channel is flushed, errors 
arising from the execution of the wrap body can be reported long 
after the wrap returns. 

In the case of a wrap that returns a value, the entire wrap body is 
transferred to the client/server communication channel, which is 
then flushed. The client-side code awaits the return of output 
values followed by a special termination value. Only then does 
the wrap return. 

See the Client Library Reference Manual for information con¬ 
cerning synchronization, run-time errors, and error handling. 
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A ERROR MESSAGES FROM THE PSWRAP TRANSLATOR 

The following is a list of error messages the pswrap translator 
can generate: 

input parameter used as a subscript is not an integer 

output parameter used as a subscript 

char input parameters must be starred or subscripted 

hex string too long 

invalid characters 

invalid characters in definition 

invalid characters in hex string 

invalid radix number 

output arguments must be starred or subscripted 
out of storage, try splitting the input file 
-s 80 is the minimum 

can’t allocate char string, try a smaller -s value 

can’t open file for input 

can’t open file for output 

error in parsing 

string too long 

usage: pswrap [-s maxstring] [-ar] [-h headerfile] [-0 outfile] [infile] 
endps without matching defineps 
errors in parsing 
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errors were encountered 


size of wrap exceeds 64K 
parameter reused 

output parameter used as a subscript 

non-char input parameter 

not an input parameter 

not a scalar type 

wrong type 

parameter index expression empty 
parameter index expression error 
end of input file/missing endps 
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B SYNTAX 


Square brackets [] mean that the enclosed form is optional. Curly 
brackets {} mean that the enclosed form is repeated, possibly 
zero times. A vertical bar I separates choices in a list. 

Unit = 

ArbitraryText {Definition ArbitraryText} 

Definition = 

NLdefineps ["static"] Ident"(" [Args] [T Args]”)” Body NLendps 

Body = 

{Token} 

Token = 

Number I PSIdent I SlashPSIdent 
I "("StringLiteral")" 

I "<"StringLiteral”>" 

P{" Body"}" 

I"[" Body ”]" 

I Input Element 


Args = 

ArgList {";" ArgList} [";"] 

ArgList = 

Type ItemList 


"DPSContext" 1 "boolean" I "float" I "double" 

I ["unsigned"] "char" I ["unsigned"] ["short" I "long"] "int" 
1 ["int” I "long" I "short" I "float"] "numstring" 


ItemList = 

Item {"," Item} 


Item = 

"*" Ident I Ident ["["Subscript"]"] 
I Ident "["Subscript"]" [Scale] 

Subscript = 

Integer I Ident 


Senile — 

":"Integer I ":"Ident 
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B.1 SEMANTIC RESTRICTIONS 


• DPSContext must be the first input argument if it appears at 
all. 

• A simple char argument (char Ident) is never allowed (must 
be * or [ ]). 

• A simple Ident item is not allowed in an output item list 
(must be * or [ ]. 


B.2 CLARIFICATIONS 

• NLdefineps matches the terminal defineps at the beginning 
of a new line. 

• NLendps matches the terminal endps at the beginning of a 
new line. 

• Ident follows the rules for C names; PSIdent follows the 
rules for PostScript language names. 

• SlashPSIdent is a PostScript language name preceded by a 
slash. 

• StringLiteral tokens follow the PostScript language conven¬ 
tions for string literals. 

• Number tokens follow the PostScript language conventions 
for numbers. 

• Integer subscripts follow the C conventions for integer con¬ 
stants. 

• Input Element is \n[i] where n is the name of an input array 
argument, i is a non-negative integer literal, and no white 
space is allowed between \ and ]. 
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C CHANGES SINCE LAST PUBLICATION OF THIS DOCUMENT 


Changes to the pswrap Reference Manual from the document 
dated January 23, 1990, are noted in the paragraphs below. 

A new pswrap data type, ‘numstring’, has been added to 
facilitate the sending of encoded number strings. 

A new command-line option, -p, specifies that strings passed by 
wraps will be padded to the next long word (four-byte) bound¬ 
ary. 

Changes to the pswrap Reference Manual from the document 
dated October 25, 1989, are noted in the paragraphs below. 

A string (‘char *’) passed as input may not be more than 65,535 
characters. An array may not contain more than 65,535 elements. 

The examples were expanded to include, in each case, the wrap 
definition, the corresponding procedure call, and the equivalent 
PostScript language code. 

Changes to the pswrap Reference Manual from the document 
dated October 6,1988, are noted in the paragraphs below. 

The manual was rewritten and reorganized. Numerous technical 
clarifications and corrections were made. 
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POSTSCRIPT* 


ENCAPSULATED POSTSCRIPT® FILES 

Specification 

Version 2.0 


June 5, 1989 

PostScript® Developer Support Group 
(415)961-4111 


This document specifies the format required for import of Encapsulated PostScript (EPS) 
Files into an application. This specification suggests a standard for importing PostScript 
language files in all environments, and contains specific information about both the 
Macintosh® and MS-DOS environments. This format conforms to Adobe Systems’ 
Document Structuring Conventions, Version 2.0. 

The rules that should be followed in creating importable PostScript language files are a 
subset of the structuring conventions proposed by Adobe Systems Incorporated; refer to the 
PostScript Language Reference Manual , Appendix C, and Document Structuring 
Conventions , version 2.0, available from Adobe Systems. Files must also be ”well- 
behaved" in their use of certain PostScript language operators, manipulation of the graphics 
state, and manipulation of the PostScript interpreter’s stacks and any global dictionaries. 
These conventions are designed to allow cooperative sharing of files between many 
systems using the PostScript language. 

Fundamentally, an EPS file is a standard PostScript language file with a bitmap screen 
preview included optionally in the format. The purpose of an EPS file is to be included into 
other document makeup systems as an illustration, and the screen representation is intended 
to aid in page composition. The bitmap is normally discarded when printing, and the 
PostScript language segment of the file is used instead. Typically any manipulation of the 
screen image that is performed by the user (such as scaling, translating, or rotation on 
screen) should be tracked by the page layout application and an appropriate transformation 
should precede the EPS file when it is sent to the printer. 


EPS FILE FORMAT GUIDELINES 

An EPS file should conform to at least Version 2.0 of the Adobe Document Structuring 
Conventions. This does not explicitly require any of the structuring comments to be 
employed, but if used, they should be in accordance with that specification. Additionally, 
an EPS file is required to contain the %%BoundingBox comment, and is required to be 
’’well-behaved” (see pages 3-4). An EPS file may optionally contain a bitmap image 
suitable for WYSIWYG screen display, as discussed herein. 

The structure of an EPS file is marked by PostScript language comments, according to the 
PostScript Document Structuring Conventions. These are covered briefly here for 
reference. Structuring comment lines must begin with "%!" or "%%" and terminate with 
a newline (either return or linefeed) character. EPS file conventions require that a comment 
line be no longer than 256 bytes. A comment line may be continued by beginning the 
continuation line with "%%+". The EPS file should begin with a header of structuring 
comments, as specified in the PostScript Structuring Conventions. 


©1989 Adobe Systems Incorporated. All rights reserved. 


3 



2. REQUIRED PARTICIPATION 


In order to support Encapsulated PostScript files effectively, some cooperation is required 
on the parts of those who produce EPS files and those who use EPS files (typically by 
including them into other documents). 

2.1 WHEN PRODUCING EPS FILES 

There are certain required comments and several recommended ones that must be provided 
in the EPS file. These are detailed in Section 3. The file must also be a single page (not a 
multiple-page document) and must be a conforming PostScript language document. 
Conformance requirements are mostly detailed here, but for the full specification, please 
refer to the Document Structuring Conventions from Adobe Systems. 

2.2 WHEN READING AND USING EPS FILES 

When including an EPS file into your document, you should basically think of that piece of 
code as having been generated by your program. After all, that is what all programs (and 
users) who encounter your print file will think. In particular, you must find out enough 
about the file to intelligently make it part of your document. The only tricky part of this 
relates to font usage. This is also the most difficult part of this specification to understand. 
Basically, you just have to figure out what the requirements of the illustration are and 
incorporate them into your own requirements (pass them downstream). Then all issues of 
font management are essentially the same as they were before you included the illustration 
(and are beyond the scope of this document). 

As long as you don’t remove relevant information from a file, and as long as you update 
your global view of font usage and resource requirements to reflect those that you just 
imported, the rest is fairly easy. The intent behind the EPS specification, in fact, is to make 
the most of cooperation between producers and consumers of PostScript language files so 
that neither has to do much, but the combined advantage is great. 

3. REQUIRED COMMENTS 

The first comment in the header (and the first line in the file) should be the version 
comment: 

%!PS-Adobe-2.0 EPSF-2.0 

This indicates to an application that the PostScript language file conforms to this standard. 
The version number following the word "Adobe-" indicates the level of adherence to the 
standard PostScript Document Structuring Conventions. The version number following the 
word "EPSF" indicates the level of EPSF-specific comments. 

The following comment must be present in the header; if it is not present then an importing 
application may issue an error message and abort the import: 

%%BoundingBox: LLx LLy URx URy 

The values are in the PostScript default user coordinate system, in points (1/72 of an inch, 
or 0.3527 mm), with the origin at the lower left comer. The bounding box must be 
expressed in default user coordinate space. This seems to be a big question among 
implementors of thk specification. Regardless of the coordinate system in which your 
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application operates, here is a foolproof way of determining the correct bounding box: 
print the page, get out a point ruler, and measure first to the lower left comer, then to the 
upper right corner, using the lower-left corner of the physical paper as your origin. This 
works because it measures the end result (the marks on the page), and none of the 
computation matters. 


OPTIONAL COMMENTS 


The following header comments are strongly recommended in EPS files. They provide 
extra information about the file that can be used to identify it on-screen or when printing. 


%%Title: included_document_title 
%%Creator: creator_name 
%%CreationDate: date_and_Jime 

The %% Creator, %% Title, and %%CreationDate comments may be used by an 
application or spooler to provide human-readable information about a document, or to 
display the file name and creator on the screen if no bitmapped screen representation was 
included in the EPS file. 


%%EndComments 

This comment indicates an explicit end to the header comments, as specified in the 
structuring conventions. 

HOW TO USE THESE COMMENTS (PHILOSOPHY) 

All of the comments in EPS files provide information of some sort or another. Exactly how 
you use this information is up to you, but you are encouraged not to reduce the amount of 
information in a file (when you import it or include it, for example) by removing or altering 
comments. In general, the comments tell you what fonts and files are used, and where. Not 
everybody cares about these things, but if you do care, then the information is available. 

The whole issue of Encapsulated PostScript files is that they are “final form” print files that 
may be far from the printer that they will actually be imaged on. If they have specific needs, 
particularly in terms of font usage, these needs must be carefully preserved and passed on 
downstream, and the program that actually prints the composite document must take pains 
to make sure the fonts are available at print time. 

Any piece of software that generates PostScript language code is potentially both a 
consumer and a producer of Encapsulated PostScript files. It is probably best not to think 
that you are at either end of the chain. In particular, if you import an Encapsulated 
PostScript file, integrate it into your document somehow, and then go to print your 
document, you are responsible for reading and understanding any of the font needs of the 
EPS file you imported. These should then be reflected in your own font usage comments. 
If the illustration on page 3 uses the Bodoni font but the rest of your document is set in 
Times, suddenly your document now also uses the Bodoni font (you included the 
illustration, after all). This should be reflected in the outermost %%DocumentFonts 
comments and any other appropriate ones. 
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4.2 FONT MANAGEMENT COMMENTS 

If fonts are used, the following two comments (which are defined in version 2.0 of the 
PostScript Document Structuring Conventions) should be included in the header of the EPS 
file. The % %IncludeFont and % % Begin/% %EndFont comments should be thought of 
as inverses of one another. That is, if you encounter an %%IncludeFont comment and 
actually include a font file at that point, you should enclose the font in % %BeginFont and 
% %EndFont comments. Conversely, if you see fit to remove a font from a print file (one 
that presumably had been delimited with comments), you should always replace it with an 
%%IncludeFont comment rather than completely stripping it. This guarantees the 
reversibility of your actions. 

%%DocumentFonts: fontl font2 .... 

%%+ font3 font4 

The % %DocumentFonts comment provides a full list of all fonts used in the file. Font 
names should refer to non-reencoded printer font names and should be the valid PostScript 
language names (without the leading slashes). An application that imports an EPS file 
should be responsible for satisfying these font needs, or at least updating its own 
% %DocumentFonts list to reflect any new fonts. 

%%DocumentNeededFonts: fontl font2 .... 

The % %DocurnentNeedec!Fonts comment lists all fonts that are to be included at specific 
points within the EPS file as a result of the % %IncludeFont comment. These fonts must 
also be listed in the % %DocumentFonts comment, but an application may or may not pre¬ 
load these at the beginning of the job. The responsibility should be taken, however, by any 
program that thinks it is actually printing the file, to make sure the fonts requested will be 
available when the file is printed. This may mean that the individual %%IncludeFont 
comments may be satisfied and the fonts placed in-line, or they may simply be ignored, if 
the fonts are determined to be already available on the printer. As a third possibility, there 
may be enough memory to download all the fonts in front of the job and avoid processing 
the individual requests. This % %DocumentNeededFonts comment provides 
foreshadowing of the %%IncludeFont comments to follow, to give printing managers 
enough information to make these choices intelligently. 

%%lncludeFont: fontname 

The % %IncludeFont comment signals to an application that the specified font is to be 
loaded at that precise location in the file. It is analogous to the familiar #include syntax in 
the C language. An application should load the specified font regardless of whether the 
same font has been loaded already by other preceding %%In£ludeFont comments, since 
the font may have been embedded within a PostScript language save and restore construct. 
However, if the font is determined to be available prior to the entire included EPS file (for 
instance, it may be in ROM in the printer or might have been downloaded prior to the entire 
print job) the % %IncIudeFont comment may be ignored by printing manager software. 

When an application satisfies an %%IncludeFont request, it should always bracket the 
font itself with the % %BeginFont and % %EndFont comments. 

A font that is wholly contained, defined, and used within the EPS file (a downloaded font) 
should be noted in the %%DocumentFonts comment, but not the 
%%DocumentNeededFonts comment. The font should follow conventions listed in the 
Document Structuring Conventions in order to retain full compatibility with print spoolers. 
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%%BeginFont: fontname 
%%EndFont 

The % %BeginFont and % %EndFont comments bracket an included downloadable font. 
The fontname is the simple PostScript language name for the font. These fonts may be 
stripped from the included file if they are determined to be available (but should be replaced 
by an % %IncludeFont comment). 

4.3 FILE MANAGEMENT COMMENTS 
%%lncludeFile: filename 

This comment, which can occur only in the body of an EPS file, allows a separate file to be 
inserted at any point within the EPS file. The file might not be searched for or inserted until 
printing actually occurs, so user care is required to ensure its availability. If it is used, the 
%%DocumentFiles comment should be used as well. See the Structuring Conventions for 
more information. 

%%BeginFile: filename 
%%EndFile 

The %%BeginFile and %%EndFile comments bracket an included file. They are the 
“inverse” of the % %IncludeFiIe comment. The filename is evaluated in the context of the 
local file system. These files may not be stripped from the included file at print time, 
because they undoubtedly contain executable code. However, they may be temporarily 
removed, or “factored out” to save space during storage. They should always be replaced 
by the % %IncludeFile comment 

4.4 COLOR COMMENTS 
%%DocumentProcessColors: keyword keyword... 

This comment marks the use of process colors within the document. Process colors are 
defined to be cyan , magenta , yellow , and black These four colors are indicated in this 
comment by the keywords Cyan, Magenta, Yellow, and Black. This comment is used 
primarily when producing color separations. The (atend) conventions is allowed. 

%%DocumentCustomColors: name name... 

This indicates the use of custom colors within a document. These colors are arbitrarily 
named by an application, and their CMYK or RGB approximations are provided through 
the %%CMYKCustomColor or %%RGBCustomCoIor comments within the body of 
the document. The names are specified to be any arbitrary PostScript language string except 
(Process Cyan), (Process Magenta), (Process Yellow), and (Process Black), which need to 
be reserved for custom color implementation by applications. The (atend) specification is 
permitted. 

%%BeginProcessColor: keyword 
%%EndProcessColor 

The keyword here is either Cyan, Magenta, Yellow, or Black. During color separation, 
the code between these comments should only be downloaded during the appropriate pass 
for that process color. Intelligent printing managers can save considerable time by omitting 
code within these bracketing comments on the other three separations. Extreme care must 
be taken by the document composition software to correctly control overprinting and 
“knockouts” if these comments are employed, since the code may or may not actually be 
executed. 
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%%BeginCustomColor: keyword 
%%EndCustomColor 

The keyword here is any PostScript language string except (Process Cyan), (Process 
Magenta), (Process Yellow), and (Process Black). During color separation, the code 
between these comments should only be downloaded during the appropriate pass for that 
custom color. Intelligent printing managers can save considerable time by omitting code 
within these bracketing comments on the other three separations. Extreme care must be 
taken by the document composition software to correctly control overprinting and 
knockouts if these comments are employed, since the code may or may not be executed. 

%%CMYKCustomColor: cyan magenta yellow black keyword 

This provides an approximation to the custom color specified by keyword . The four 
components of cyan, magenta, yellow, and black must be specified as numbers from 0 to 
1 representing the percentage of that process color. These numbers are exactly analogous 
to the arguments to the setcmykcolor PostScript language operator. The keyword follows 
the same custom color naming conventions for the %%DocumentCustomColors 
comment. 

%%RGBCustomColor: red green blue keyword 

This provides an approximation to the custom color specified by keyword. The three 
components of red, green, and blue must be specified as numbers from 0 to 1 representing 
the percentage of that process color. These numbers are exactly analogous to the arguments 
to the setrgbcolor PostScript language operator. The keyword follows the same custom 
color naming conventions for the % %DocumentCustomColors comment. 


5. “WELL-BEHAVED” RULES 


An application should encapsulate the imported EPS code in a save / restore construct, 
which will allow all printer VM (memory) to be recovered and all graphics state restored. 
Since the code in the imported EPS file will be embedded within the PostScript language 
that an application will generate for the current page, it is necessary that it obey the 
following rules, in order to keep from disrupting the enclosing document: 


5.1 OPERATORS TO AVOID 

The following PostScript operators should not be included in a PostScript language file for 
import; the result of executing any of these is not guaranteed (see the PostScript Document 
Structuring Conventions for more on this): 


grestoreall 

erasepage 

nulldevice 

exitserver 


initgraphics 

copypage 

renderbands 

setscreen* 


initmatrix 

banddevice 

setpageparams 

settransfer* 


initclip 

framedevice 

note 


5.2 THE ‘SETSCREEN’ AND ‘SETTRANSFER’ OPERATORS 

The setscreen operator is troublesome when one file is included within another, setscreen 
is a system-level command that is appropriate for changing the halftone machinery to 
compensate for marking engine tendencies, but when used for “special effects” can cause 
problems. For EPS files, the setscreen and settransfer operators are permitted only under 
restricted terms. 
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THE ‘SETTRANSFER’ AND ‘SETCOLORTRANSFER’ 
OPERATORS 

The settransfer operator changes the gray-level and color response curves over the interval 
from 0 to 1. There are two basic uses of it: to invert an image (typically flipping blacks and 
whites, less often colors), or to adjust the response curve for a particular output device. 

The best (and required) approach for using settransfer is to combine your function with 
the existing one. Here is the recommended way to do this: 

{ dummy exec 1 exch sub } dup 0 currentransfer put settransfer 

In this example, the desired transfer function is the code 1 exch sub. The dummy exec 
essentially executes the existing transfer function before executing the new code. The name 
dummy is replaced by the actual procedure body from the existing transfer function 
through the put instruction. The result is conceptually equivalent to this: 

{{original proc } exec 1 exch sub } settransfer 

This approach is better than “concatenating” procedures because it does not require the 
existing transfer function to be duplicated (consuming memory). 

THE ‘SHOWPAGE’ OPERATOR 

The showpage operator is permitted in EPS files primarily because it is present in so many 
PostScript language files. It is reasonable for an EPS file to use the showpage operator if 
needed (although it is not necessary if the file is truly imported into another document). It 
is the including application’s responsibility to disable showpage if needed. The 
recommended method to accomplish this is as follows: 

TEMPORARILY DISABLING ‘SHOWPAGE’ 

/BEGINEPSFILE { %def 
/EPSFsave save def 

0 setgray 0 setlinecap 1 setlinewidth 0 setlinejoin 10 setmiterlimit [] 0 setdash 
newpath 

/showpage {} def 
} bind def 

/ENDEPSFILE {%def 

EPSFsave restore 
} bind def 

BEGINEPSFILE 
100 300 translate 
.5 .5 scale 

% include the EPS file here, which may execute showpage with no effect 
ENDEPSFILE % restore state and continue 

This method will only disable the showpage operator during the execution of the EPS file, 
and will restore the previous semantics of showpage afterward. It is the responsibility of 
the EPS file itself to avoid the operators listed in the previous section that might cause 
unexpected behavior when imported. They need not be redefined along with showpage, 
although it is permissible to do so. 
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5.4 STACKS AND DICTIONARIES 

All of the PostScript interpreter’s stacks (including the dictionary stack) should be left in 
the state that they were in before the imported PostScript language code was executed. This 
is normally the case for well-written PostScript language programs, and this is still the best 
way to keep unanticipated side-effects to a minimum. Please avoid unnecessary clear and 
M countdictstack 2 sub { end } repeat" cleanup techniques. If you have accidentally left 
something on one of the stacks, it is best to understand your program well enough to get rid 
of it, rather than issuing a wholesale cleanup instruction at the end, which will not only clear 
your operands from the stack, but perhaps will clear other objects as well. 

It is recommended that the imported EPS file create its own dictionary instead of writing 
into whatever the current dictionary might be. Make sure that this dictionary is removed 
from the dictionary stack when through (using the PostScript language end operator) to 
avoid the possibility of an invalidrestore error. Also, no global string bodies should be 
changed (with either put or putinterval). 

If a special dictionary (like statusdict) is required in order for the imported PostScript 
language code to execute properly, then it should be included as part of the EPS file. 
However, it should be enclosed in very specific % %BeginFeature and % %EndFeature 
comments as specified in the Document Structuring Conventions. No dictionary should be 
assumed to be present in the printer, and fonts should be reencoded as needed by the EPS 
file itself. 

5-5 THE GRAPHICS STATE 

When a PostScript language program is imported into the middle of another executing 
program, the state of the interpreter may not be exactly in its default state. The EPS file 
should assume that the graphics state is in its default state, even though it may not be. An 
importing application may choose to scale the coordinate system or to change the transfer 
function to change the behavior of the EPS file somewhat. If the EPS file makes 
assumptions about the graphics state (like the clipping path) or explicitly sets something it 
shouldn’t (the transformation matrix), the results may not be what were expected. 


The importing application is responsible for returning the color to be black, the current dash 
pattern, line endings, and other miscellaneous aspects of the graphics state to their default 
condition (as specified in the PostScript Language Reference Manual). This can be done in 
either of two ways: the initial graphics state can be restored from variables, or the state can 
be explicitly set: 

/BEGINEPSFILE {%def 
/EPSFsave save def 

0 setgray 0 setlinecap 1 setlinewidth 0 setlinejoin 10 setmiterlimit [] 0 setdash 
newpath 

/showpage {} def 
} bind def 

/ENDEPSFILE {%def 
EPSFsave restore 
} bind def 
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6. FILE TYPES AND FILE NAMING 

APPLE MACINTOSH FILES 

The Macintosh file type for application-created PostScript language files is EPSF. Files of 
type TEXT will also be allowed, so that users can create EPS files with standard editors, 
although the Structuring Conventions must still be strictly followed. A file of type EPSF 
should contain a PICT resource in the resource fork of the file containing a screen 
representation of the PostScript language code. The file name itself may follow any naming 
convention as long as the file type is EPSF. If the file type is TEXT, the extensions .epsf 
and .epsi, respectively, should be used for the Macintosh-specific format and EPSI 
interchange format. 

MS-DOS AND PC-DOS FILES 

The recommended file extension is .EPS. For EPSI files, the extension should be .EPI. 
Other file extensions also can be used, but it will be assumed that these files are text-only 
files with no screen metafile included in them. 

OTHER FILE SYSTEMS 

In general, the extension .epsf is the preferred way to name an EPS file, and .epsi for the 
interchange format. In systems where lower-case letters are not recognized or are not 
significant, all upper-case can be used. 


7. SCREEN REPRESENTATIONS 

The EPS file will usually have a graphic screen representation so that it can be manipulated 
and displayed on a workstation’s screen prior to printing. The user may position, scale, 
crop or rotate this screen representation, and the composing software should keep track of 
these manipulations and reflect them in the PostScript language code that is ultimately sent 
to the printing device. 

The exact format of this screen representation is machine-specific. That is, each computing 
environment may have its own preferred bitmap format, and that is typically the appropriate 
screen representation for that environment. An interchange representation is specified that 
should be implemented by everyone, and any environment-specific formats can be 
supported in addition, as deemed appropriate. 

7.1 APPLE MACINTOSH: PICT RESOURCE 

A QuickDraw™ representation of the PostScript language file can be created and stored as 
a PICT in the resource fork of the file. It should be given resource number 256. If the PICT 
exists, the importing application may use it for screen display. If the picframe is 
transformed to PostScript language coordinates, it should agree with the 
% %BoundingBox comment. 

Given the size limitations on PICT images, this may not always agree for large illustrations. 
If there is a discrepancy, the %%BoundingBox always should be taken as the ’’truth”, 
since it accurately describes the area that will be imaged by the PostScript language code 
itself. In this situation, applications producing the preview PICT must all take the same 
action so that the importing application knows what to do. 
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Since it is more important to have a reasonable facsimile of the image than it is to have any 
particular part of it be high quality, the PICT image should be scaled to fit within the 
constraints of the PICT format. That is, the picture will all be there (it will not be cropped), 
but it will actually be smaller than the real image. The importing application should then 
scale the PICT to a size which matches the bounding box as expressed in the 
%%BoundingBox comment. 

7.2 PC/DOS: WINDOWS METAFILE OR TIFF FILE 

Either a Microsoft® Windows Metafile or a TIFF (Tag Image File Format) section can be 
included as the screen representation of an EPS file. 

The EPS file itself has a binary header added to the beginning that provides a sort of “table 
of contents” to the file. This is necessary since there is not a second “fork” within the file 
system as there is in the Macintosh file system. 

NOTE: 

It is always permissible to have a pure ASCII PostScript language file as an EPS 
file in the DOS environment, as long as it does not contain the preview section. 

The importing application should check the first three bytes of the file. If they 
match the header as shown below, the binary header should be expected. If the 
first two match %!, it should be taken to be an ASCII PostScript language file. 


DOS EPS Binary File Header 


Bytes 

Description 

0-3 

Must be hex C5D0D3C6 (byte 0=C5) 

4-7 

Byte position in file for start of 

8-11 

PostScript language code section. 

Byte length of PostScript language section 

12-15 

Byte position in file for start of Metafile 

16-19 

screen representation. 

Byte length of Metafile section (PSize) 

20-23 

Byte position of TIFF representation 

24-27 

Byte length of TIFF section 

28-29 

Checksum of header (XOR of bytes 0-27) 

Note: 

NOTE: if Checksum is FFFF then it is to be ignored. 


It is assumed that either the Metafile or the TIFF position and length fields are 
zero; that is, only one or the other of these two formats is included in the EPS file. 

The Metafile should follow the guidelines set forth by the Windows specification. In 
particular, it should not set the viewport or mapping mode, and it should set the window 
origin and extent. The application should scale the picture to fit within the 
%%BoundingBox comment specified in the PostScript language file. 


8. DEVICE-INDEPENDENT INTERCHANGE FORMAT 

This last screen representation is intended as an interchange format between widely varied 
systems. In particular, the bitmap preview section of the file is very simple and is 
represented as ASCII hexadecimal in order to be more easily transportable. This format is 
dubbed Encapsulated PostScript Interchange format, or “EPSI.” 
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This format wins no prizes for compactness, but it should be truly portable and requires no 
special code for decompressing or otherwise understanding the bitmap portion, other than 
the ability to understand hexadecimal notation. 

It is expected that applications that support EPSF will gradually head toward supporting 
only two formats: the first is the “native” format for the environment in which the 
application runs (where the preview section is Macintosh PICT or TIFF or Sun raster files 
or whatever); the second format should simply be this interchange format. Then files can 
be interchanged between widely varying systems without each having to know the 
preferred bitmap representation of the others. 

%%BeginPreview: width height depth lines 
%%EndPreview 

These comments bracket the preview section of an EPS file in Interchange format (EPSI). 
The width and height fields provide the number of image samples (pixels) for the preview. 
The depth field provides how many bits of data are used to establish one sample pixel of 
the preview (1, 2, 4, or 8). An image which is 100 pixels wide will always have 100 in the 
width field, although the number of bytes of hexadecimal needed to build that line will vary 
if depth varies. The lines field tells how many lines of hexadecimal are contained in the 
preview, so that they may be easily skipped by an application that doesn’t care. All the 
arguments are integers. 

SOME RULES AND GUIDELINES FOR “EPSI” FILES 

The following guidelines attempt to clarify a few basic assumptions about the EPSI format. 
It is intended to be extremely simple, since its purpose is interchange. No system should 
have to do much work to decipher one of these files, and the preview section is mostly just 
a convenience to begin with. This format is accordingly deliberately kept simple and 
option-free. 

• The preview section must be after the header comment section but before the document 
prologue definitions. That is, it should immediately follow the % %EndComments line 
in the EPS file. 

• In the preview section, 0 is white and 1 is black, in deference to the majority. Arbitrary 
transfer functions and “flipping” black and white are not supported. 

• The Preview image can be of any resolution. The size of the image is determined solely 
by its bounding box , and the preview data should be scaled to fit that rectangle. Thus, the 
width and height parameters from the image are not its measured dimensions, but 
simply describe the amount of data supplied for the preview. The dimensions are 
described only by the bounding rectangle. 

• The hexadecimal lines must never exceed 255 bytes in length. In cases where the preview 

is very wide, the lines must be broken. The line breaks can be made at any even number 
of hex digits, since the dimensions of the finished preview are established by the width, 
height, and depth values. 

• All non-hexadecimal characters should be ignored when collecting the data for the 
preview, including tabs, spaces, newlines, percent characters, and other stray ASCII 
characters. This is analogous to the PostScript language readhexstring operator. 
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• Each line of hexadecimal will begin with a percent sign (‘%’). This makes the entire 
preview section into a PostScript language comment, so that the file can be printed 
without modification. 

• If the %%IncludeFile or %%BeginFile / %%EndFile comments are ever used to 
extract the preview section from the EPS file, then the lines argument to the 
% %BeginPreview comment must be adjusted accordingly. The lines value specifies 
only the number of lines to skip if you’re not the least bit interested. 

• If the width of the image is not a multiple of 8 bits, the hexadecimal digits are padded 
out to the next highest multiple of 8 bits. 
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EXAMPLE “EPSI” FILE 


Here is a sample file showing the EPS Interchange (EPSI) format. The preview section is 
expressed in user space and the correct comments are included. Remember that there are 8 
bits to a byte, and that it requires 2 hexadecimal digits to represent one binary byte. 
Therefore the 80-pixel width of the image requires 20 bytes of hexadecimal data, which is 
(80 / 8) * 2. The PostScript language segment itself simply draws a box, as can be seen in 
the last few lines. 


%! PS-Adobe-2.0 EPSF-2.0 
%%BoundingBox: 0 0 80 24 
%%Pages: 0 
%%Creator: Glenn Reid 
%%CreationDate: September 19,1988 
%%EndComments 
%%BeginPreview: 80 24 1 24 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFO000000000000000FF 
% FF0000000000000000FF 
% FFOOOOOOOOOOOOOOOOFF 
% FFOOOOOOOOOOOOOOOOFF 
% FFOOOOOOOOOOOOOOOOFF 
% FFOOOOOOOOOOOOOOOOFF 
% FFOOOOOOOOOOOOOOOOFF 
% FFOOOOOOOOOOOOOOOOFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
% FFFFFFFFFFFFFFFFFFFF 
%%EndPreview 
%%End Prolog 
%%Page: "one" 1 

4 4 moveto 72 0 rlineto 0 16 rlineto -72 0 rlineto closepath 

8 setlinewidth stroke 
%%Trailer 
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1 ABOUT THIS MANUAL 


This document contains: 

• A description of the extensions to the PostScript® language 
that support new color functionality. 

• Detailed information on the associated color operators. 

Section 2 provides a general introduction to color functionality 
in the PostScript language. 

Section 3 discusses the extended color capabilities of the 
PostScript language. 

Section 4 contains an alphabetical listing of descriptions for all 
color operators that have been added to the PostScript language. 

Appendix A lists changes to the manual since the previous 
version. 


2 ABOUT THE POSTSCRIPT LANGUAGE COLOR EXTENSIONS 

The PostScript language has been extended to provide more 
complete color functionality. This includes cyan-magenta- 
yellow-black (CMYK) color specification, black generation and 
undercolor removal functions, screen and transfer functions for 
four separate color components, and extension of the image con¬ 
cept to a colorimage operator that accepts multiple color com¬ 
ponents. 

Earlier versions of the PostScript language support color using 
the setrgbcolor and sethsbcolor operators, which enable the 
PostScript interpreter to paint filled regions, strokes, image 
masks, and characters in color. On black-and-white machines, 
these operators generate an equivalent gray shade, which is 
printed or displayed. 

To support color more fully, the PostScript language has been 
extended to provide the following functions: 

• Most significantly, multiple color images: the colorimage 
operator renders a multiple color image; it functions 
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analogously to the the image operator, but uses red-green- 
blue (RGB) or cyan-magenta-yellow-black (CMYK) color 
input and generates full-color output. 

• Halftone screen definitions: the setcolorscreen operator 
specifies halftone screen definitions for red, green, blue, 
and gray, or cyan, magenta, yellow, and black concurrently; 
it is the logical expansion of setscreen as it takes the same 
three arguments to define each screen for each printing ink. 

• Color correction: the setcolortransfer operator sets the 
transfer function parameters for red, green, blue, and gray; 
it is an expansion of settransfer to four color components. 
The setblackgeneration operator provides a black genera¬ 
tion function that establishes a black component from a 
cyan, magenta, and yellow specification. The 
setundercolorremoval operator provides undercolor 
removal from the cyan, magenta, and yellow components to 
compensate for the addition of black by the black genera¬ 
tion function. 

• CMYK color specification: the setcmykcolor operator al¬ 
lows the user to set the current color in the graphics state to 
a cyan-magenta-yellow-black color directly, bypassing the 
color correction operators. 

The PostScript language supports one-color, three-color, and 
four-color output devices. The color devices can be binary (one- 
bit-per-pixel per color component) or grayscale (multiple-bits- 
per-pixel per color component, representing a range of intensities 
of each color component). A binary device uses halftoning to 
produce intermediate shades of its color components. A device 
that has eight-bits-per-pixel per component, called a full 
grayscale device, does not use halftoning. Devices with more 
than one and fewer than eight bits per pixel use a combination of 
built-in intensities and halftoning to produce the full range of 
desired shades of their color components. Three-color devices 
may be either red-green-blue (RGB), typically for displays and 
film recorders, or cyan-magenta-yellow (CMY) for printers. 
Four-color devices are cyan-magenta-yellow-black (CMYK) for 
color printers and color separation making devices. 

The color operators described in this document are available in 
two forms. Some new versions of the PostScript interpreter have 
these operators built in. For other versions of the PostScript in- 
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terpreter, a package of PostScript language programs that emu¬ 
late these operators is available. 


3 NEW FEATURES 

The color extensions to the PostScript language include CMYK 
color specification, black generation, and undercolor removal. 
Because black generation and undercolor removal use 
procedures, they allow you to adjust the conversion from RGB to 
CMYK values, for example, by producing less black in black 
generation. 

Operators are provided that allow full color input and output for 
screens, transfer functions, and images. The new color features 
are described conceptually in Sections 3.1 through 3.6. The cor¬ 
responding operators are documented in Section 4. The new 
operators are identified on first mention by an asterisk; for ex¬ 
ample, colorimage*. 

3.1 CONVERSION OF RGB VALUES TO CMYK 

Colors are formed either by adding light to black or by subtract¬ 
ing light from white. Computer displays and film recorders typi¬ 
cally add colors, while printing inks typically subtract colors. 
These two methods for forming colors give rise to the two major 
complementary color specifications, the additive RGB specifica¬ 
tion and the subtractive CMYK specification. 

Accordingly, a color component in these specifications either in¬ 
dicates the amount of light it reflects or the amount of light it 
absorbs. Each one of three standard printing process colors, 
cyan, magenta, and yellow, absorb one of the standard light com¬ 
ponents, red, green, and blue, respectively. Black, a fourth stan¬ 
dard printing process color, absorbs all components of light. In 
the red-green-blue (RGB) color specification, each of its red, 
green, and blue components is associated with a real number be¬ 
tween 0.0 and 1.0, inclusive, where 0.0 represents dark (no light) 
and 1.0 represents full light. In the cyan-magenta-yellow-black 
(CMYK) color specification, each of the four components is as¬ 
sociated with real numbers between 0.0 and 1.0 inclusive, where 
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0.0 represents full light (no ink), and 1.0 represents dark (full 
ink). 


The following equations demonstrate the relationship between 
the RGB and CMYK color specifications. Since cyan is the ab¬ 
sence of red light, magenta is the absence of green light, and 
yellow is the absence of blue light, 


cyan = 1.0- red 
magenta =1.0- green 
yellow =1.0- blue 


A color that is 0.2 red, 0.7 green, and 0.4 blue can also be ex¬ 
pressed as 1.0 - 0.2 = 0.8 cyan, 1.0 - 0.7 = 0.3 magenta, and 1.0 
- 0.4 = 0.6 yellow. To improve the fidelity of blacks and grays, a 
fourth process color, black, is often available on color printers. 
Just as red in the RGB specification is the opposite of cyan in the 
CMYK specification, a black value is the opposite to a 
PostScript language gray value; that is, 


black =1.0- gray. 


3.2 BLACK GENERATION AND UNDERCOLOR REMOVAL 

Logically, cyan, magenta, and yellow are all that are needed to 
generate a printing color completely. Thus an equal percentage 
of cyan, magenta, and yellow should create the equivalent per¬ 
centage of black. In reality, colored printing inks do not mix per¬ 
fectly, and such combinations often form dark brown shades in¬ 
stead. Thus, it is often desirable to substitute real black ink for 
the mixed-black portion of a color to obtain a truer color ren¬ 
dition on a printer. 

Black generation is the process of calculating the amount of 
black to be used when trying to print a particular color. 
Undercolor removal is the process of reducing the amount of 
cyan, magenta, and yellow components to compensate for the 
amount of black that was added by the black generation. 
Flexibility in performing these functions is important for achiev¬ 
ing good results under different printing conditions. 

The setblackgeneration* operator provides the functionality to 
generate extra black, no black, or a black value equal to all or a 
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fraction of the minimum values of cyan, magenta and yellow. Its 
argument is a procedure that takes one numeric argument, the 
minimum value of user cyan, magenta, and yellow color com¬ 
ponents, and returns a single numeric result, the user black value 
(where a user color component value is that specified in the 
PostScript language program before application of the cor¬ 
responding transfer function). This procedure is automatically 
applied whenever setrgbcolor, the three-color case of 
color image*, or sethsbcolor specifies a color. This user black 
value is then mapped to a device black value by applying the 
gray transfer function to its difference from 1.0 and subtracting 
the result from 1.0 (see setcolortransfer*). The black generation 
function is not applied when setgray, setcmykcolor*, or the one- 
or four-color cases of colorimage specifies colors. This com¬ 
puted black value is used only when producing output on four- 
color devices. 

The setundercolorremoval* operator provides functionality to 
remove some amount of color from each of the cyan, magenta, 
and yellow components. This amount could be exactly the same 
amount as was generated to make the black component, zero (so 
no color is removed from the cyan, magenta and yellow 
components), some fraction of the black amount, or even a nega¬ 
tive amount. Like setblackgeneration, this operator permits 
considerable flexibility in color correction. 

The argument to setundercolorremoval is a procedure that takes 
one numeric argument, the minimum value of user cyan, 
magenta, and yellow color components, and returns a single 
numeric result that is subtracted from each of these original user 
color components. This procedure is applied whenever 
setrgbcolor, the three-color case of colorimage, or sethsbcolor 
specifies a color. After subtracting the value generated in the 
above mapping from the color components and resetting nega¬ 
tive values to 0.0 and values greater than 1.0 to 1.0, each com¬ 
ponent is subtracted from 1.0 to yield red, green, and blue com¬ 
ponents. Each of these components is mapped into a device color 
component using its respective transfer function (see 
setcolortransfer). Undercolor removal is not applied when 
setgray, setcmykcolor, or the one- or four-color cases of 
colorimage specifies a color. Undercolor removal is used only 
when outputting on four-color devices. 
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The following three sets of equations define the complete color 
transformation process from RGB to CMYK. In the first set of 
equations, the values red u , grn u , and blu u are supplied by the 
user. gry u and blk u are assigned the values 1.0 and 0.0, respec¬ 
tively. 


cyn u = 1.0- red u 
mag u = 1.0-grn u 
yel u = 1.0 - blu u 

gry u = 1 -o 

blk u = 0.0 

In the second set of equations, k is the minimum value of cyn u , 
mag u , and yel u . u is the amount of undercolor removal; it is 
determined by the applying the undercolor removal procedure to 
the value of k. UCR() is the undercolor removal procedure. 

k = Min(cyn u , mag u ,yel u ) 
u = UCR(k) 

In the third set of equations, BG() is the black generation proce¬ 
dure. RedT, GrnT, BluT, and GryT are the red, green, blue, and 
gray transfer functions (see setcolortransfer), respectively. The 
result of applying these equations is to produce CMYK output 
values for the device. 

The values red d , grn d , blu d , and gry d are intermediate values 
used to compute cyn d , mag d , yel d , and blk d , which can be sent to 
a CMYK device. 

red d = RedT(1.0 - Min(1.0, Max(0.0, cyn u - u))) 

gm d = GrnT(1.0 - Min(1.0, Max(0.0, mag u - u))) 

blu d = BluT(1.0 - Min(1.0, Max(0.0, yel u - u))) 

gry d = GryT(1.0 - BG(k)) 

cyn d = 1.0 - red d 

mag d = 1.0 - grn d 

yel d = 1.0- blu d 

blk d = 1.0 - gry d 


3.3 DIRECT CMYK COLOR SPECIFICATION 

For the most demanding cases, color matching can require more 
complicated methods than those described above. The 
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setcmykcolor operator and the four-color case of the 
colorimage operator bypass the black generation and undercolor 
removal operations, allowing the knowledgeable user to specify 
the cyan, magenta, yellow, and black color components for a 
particular device. These operators do not provide correction 
other than the transfer functions that setcolortransfer specifies; 
the results are device dependent. 

The following equations define the complete color transfor¬ 
mation process for the setcmykcolor operator and the four-color 
case of the colorimage operator. They are equivalent to those 
given in Section 3.2 except for the omission of the black genera¬ 
tion and undercolor removal steps. The values are the same as 
those defined in Section 3.2. 

red u = 1.0- cyn u 
grn u = 1.0- mag u 
blu u = 1.0-yel u 
gry u = 1.0-blk u 
red d = RedT(red u ) 
grn d = GrnT(grn u ) 
blu d = BluT(blu u ) 
gry d = GryT(gry u ) 
cyn d = 1.0- red d 
mag d = 1.0 - grn d 
yel d = 1.0 - blu d 
blk d = 1.0 - gry d 


3.4 COLOR SCREENS, TRANSFER FUNCTIONS, AND IMAGES 

The operators setcolorscreen, currentcolorscreen, 
setcolortransfer, and currentcolortransfer provide an expan¬ 
sion of the operators setscreen, currentscreen, settransfer, and 
currenttransfer, respectively, by setting up a screen and a trans¬ 
fer function for each color component. The colorimage operator 
provides an expansion of the image operator to allow samples of 
one, three, or four color components. 
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3.5 THE COLORIMAGE OPERATOR 

colorimage is the logical expansion of image to handle sampled 
images whose samples are composed of color components rather 
than gray values. The initial arguments to colorimage are the 
same as those for image. The final arguments differ according to 
the number of color components per sample and according to the 
encoding method. 

The arguments to colorimage are shown below; see Section 4 
for precise definitions of these arguments: 

width height bits/component matrix proc 0 [...proc nco)ors _i] multiproc ncolors 

ncolors describes the number of color components in each 
sample. Legal values for ncolors are 1 (gray-level samples only), 
3 (RGB samples), or 4 (CMYK samples), multiproc is a boolean 
that distinguishes between encoding methods. When multiproc is 
false, there is a single procedure and color components are 
bunched together; when multiproc is true, there are multiple 
procedures, one per color, and components are separated into 
strings of like colors. 

The legal variations of ncolors and multiproc allow the follow¬ 
ing possibilities (where proc subscripts have been changed to 
words to indicate the purpose of each procedure): 

w h b/c matrix proc gray false 1 
w h b/c matrix proc gray true 1 
w h b/c matrix proc rgb false 3 
w h b/c matrix proc red proc green proc blue true 3 
w h b/c matrix proc cmyk false 4 

w h b/c matrix proc cyan proc magenta proc ye||ow proc b|ack true 4 
The first two variations here are both equivalent to 
w h b/s matrix proc gray image 

Data formats for colorimage operator. As indicated above, the 
colorimage operator has two forms, distinguished by its 
multiproc argument. 

The single-procedure form is most useful if sample input is taken 
from a source that has already merged the color components. 
This form provides samples for which each RGB triple or 


8 


PostScript Language Color Extensions / Version of January 23,1990 



CMYK quadruple is packed together in the string result of the 
procedure, using one of the following bit formats (where the 
high-order bit is shown on the left): 

Bits/ 
comp. 

1 RGBRGBRG 

2 RRGGBBRR 

4 RRRRGGGG 

8 RRRRRRRR 

or 

Bits/ 

comp. CMYK Format 

1 CMYKCMYK CMYKCMYK CMYKCMYK CMYKCMYK .... 

2 CCMMYYKK CCMMYYKK CCMMYYKK CCMMYYKK .... 

4 CCCCMMMM YYYYKKKK CCCCMMMM YYYYKKKK 

8 CCCCCCCC MMMMMMMM YYYYYYYY KKKKKKKK 

The multiple-procedure form expects each procedure to return a 
string of values for only one color component per sample, using 
the same format as strings returned by the proc argument of the 
image operator. For a three-color image, proc 0 returns red 
values, proc^ returns green values, and proc 2 returns blue values. 
For a four-color image, proc 0 returns cyan values, proc j returns 
magenta values, proc 2 returns yellow values, and proc 3 returns 
black values. The colorimage operator calls each of these 
procedures in turn, starting with proc Q and continuing with 
procy proc 2 , and, if available, procy When the colorimage 
operator needs more samples, it calls these procedures again in 
the same order. The color procedures must use separate strings 
for the three or four results of the three or four procedures; that 
is, reusing the red string for the green values may cause some of 
the red values to be lost. Also, the three or four procedures must 
return strings of identical lengths within each cycle of three or 
four calls. 

The multiple-procedure form is most useful when color sample 
data are taken from separate color scanner passes. The 
colorimage operator requires the color data to be interleaved, 
since the operator requires all three or four components of any 
sample at the same time in order to do its work. The single¬ 
procedure form interleaves the data at the sample level; this may 
be convenient only if the data are already in that form when 
preparing the PostScript language page description. The 


RGB Format 

BRGBRGBR GBRGBRGB RGBRGBRG 
GGBBRRGG BBRRGGBB RRGGBBRR 
BBBBRRRR GGGGBBBB RRRRGGGG 
GGGGGGGG BBBBBBBB RRRRRRRR 
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multiple-procedure form allows interleaving at a much coarser 
level. Typically, each procedure of the multiple-procedure form 
returns components for some number of scan lines of samples, 
where the number of components returned at each call is limited 
by the string storage available in the PostScript interpreter. 

Examples of colorimage operator. The following examples il¬ 
lustrate the use of the colorimage operator: 

EXAMPLE 1: 

/rgbstr 192 string def % string to hold 256 two-bit samples 
% each of red, green, and blue data 
45 140 translate % locate lower left corner of image 
132 132 scale % map image to 132 point square 

256 256 2 % dimensions of source image 

[256 0 0 -256 0 256] % map unit square to source 

{currentfile % read image data from program file 

rgbstr readhexstring pop} 

false 3 % single proc, 3 colors, bit format: 

% rrggbbrr ggbbrrgg bbrrggbb ... 

colorimage 

94a1bec8c0b371a3a5c4d281 ... (98304 hex digits of image data) 

The code fragment above shows a one-procedure, 2-bit RGB image. 
The base-4 representation of the hexadecimal data is 

2110 2201 2332 ... 

which is composed of the following color samples: 

r=2 g=1 b=1 r=0 g=2 b=2 r=0 g=1 b=2 r=3 g=3 b=2 ... 


10 


PostScript Language Color Extensions / Version of January 23,1990 



EXAMPLE 2: 

/rstr 256 string def % string to hold 256 8-bit red samples 

/gstr 256 string def % string to hold 256 8-bit green samples 

% (distinct from rstr) 

/bstr 256 string def % string to hold 256 8-bit blue samples 
% (distinct from rstr and bstr) 

45 140 translate % locate lower left corner of image 

132 132 scale % map image to 132 point square 

256 256 8 % dimensions of source image 

[256 0 0 -256 0 256] % map unit square to source 

{currentfile rstr readhexstring pop) 

% read red data from program file 
{currentfile gstr readhexstring pop) 

% read green data from program file 
{currentfile bstr readhexstring pop} 

% read blue data from program file 
true 3 % multiple proc, 3 colors 

colorimage 

7b5e606969615365556a6a66 ... (512 hex digits of red data) 

88868d848a92878578787a82 ... (512 hex digits of green data) 

62717c7b736e707d7b6a7c79... (512 hex digits of blue data) 

7d8b8d8c837d8b8e9284878e... (512 hex digits of red data) 

2788b838b8e8e86868988908 ... (512 hex digits of green data) 

81817d857f85858290949487 ... (512 hex digits of blue data) 

... (390144 more hex digits of RGB data, cycling as above) 

The code fragment above shows a three-procedure, 8-bit RGB image. 
The initial samples for each color, in hexadecimal representation, are 


red: 

7b 

5e 

60 

69 

green: 

88 

86 

8d 

84 

blue: 

62 

71 

7c 

7b 
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EXAMPLE 3: 

/cstr 128 string def % string to hold 256 4-bit cyan samples 

/mstr 128 string def % string to hold 256 4-bit magenta samples 

% (distinct from cstr) 

/ystr 128 string def % string to hold 256 4-bit yellow samples 
% (distinct from cstr and mstr) 

/kstr 128 string def % string to hold 256 4-bit black samples 
% (distinct from cstr, mstr, and ystr) 

45 140 translate % locate lower left corner of image 

132 132 scale % map image to 132 point square 

256 256 4 % dimensions of source image 

[256 0 0 -256 0 256] % map unit square to source 

(currentfile cstr readhexstring pop) 

% read cyan data from program file 
(currentfile mstr readhexstring pop) 

% read magenta data from program file 
(currentfile ystr readhexstring pop) 

% read yellow data from program file 
(currentfile kstr readhexstring pop) 

% read black data from program file 
true 4 % multiple proc, 4 colors 

colorimage 

e1d8caa57b655b6779606b72 ... (256 hex digits of cyan data) 

6bdbb867b9fb6a4859569989 ... (256 hex digits of magenta data) 

996796e639cc0b29f94736c7 ... (256 hex digits of yellow data) 

C9c0cad0d3cad2b7c9e2d7d8 ... (256 hex digits of black data) 

5d2d6d7d4d3d 1 d4d6c9d4d9d ... (256 hex digits of cyan data) 

4cdcfd4d6d1d8d7d5d4d2d2d ... (256 hex digits of magenta data) 

d2b7c9e2d7d8d8cbbac2d9d8 ... (256 hex digits of yellow data) 

88ae96632a70f6f4d8d9d9d8 ... (256 hex digits of black data) 

... (260096 more hex digits of CMYK data, cycling as above) 

The code fragment above shows a four-procedure, four-bit CMYK 
image. The initial samples for each color, in hexadecimal represen¬ 
tation, are 

cyan: e 1 d 8 c a a 5 ... 

magenta: 6 b d b b 8 6 7 ... 

yellow: 9 9 6 7 9 6 e 6 ... 

black: c9c0cad0... 
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EXAMPLE 4: 

/cstr 1024 string def % string to hold 1024 8-bit cyan samples 

/mstr 1024 string def % string to hold 1024 8-bit magenta samples 

% (distinct from cstr) 

/ystr 1024 string def % string to hold 1024 8-bit yellow samples 
% (distinct from cstr and mstr) 

/kstr 1024 string def % string to hold 1024 8-bit black samples 
% (distinct from cstr, mstr, and ystr) 

/cfile (img/smp.c) (r) file def % binary file containing 1048576 8-bit 

% cyan samples 

/mfile (img/smp.m) (r) file def % binary file containing 1048576 8-bit 

% magenta samples 

/yfile (img/smp.y) (r) file def % binary file containing 1048576 8-bit 

% yellow samples 

/kfile (img/smp.k) (r) file def % binary file containing 1048576 8-bit 

% black samples 

36 126 translate % locate lower left corner of image 
540 540 scale % map image to 540 point square 

1024 1024 8 % dimensions of source image 

[1024 0 0 -1024 0 1024] % map unit square to source 

{cfile cstr readstring pop) % read cyan data from img/smp.c 

{mfile mstr readstring pop) % read magenta data from img/smp.m 
{yfile ystr readstring pop) % read yellow data from img/smp.y 

{kfile kstr readstring pop) % read black data from img/smp.k 

true 4 % multiple proc, 4 colors 

colorimage 

The code fragment above shows a four-procedure, 8-bit CMYK 
image, with cyan, magenta, yellow, and black samples taken 
from the files img/smp.c, img/smp.m, img/smp.y, and img/smp.k, 
respectively. This example only applies to a PostScript inter¬ 
preter that has a file system. 

3.6 COLOR IMPLEMENTATIONS 

Each PostScript interpreter uses default color output methods 
that correspond to its target printer. If the printer is a direct-color 
binary device, the standard output method produces three- or 
four-color output. If the printer is a grayscale color device, the 
PostScript interpreter uses a grayscale three- or four-color output 
method. If the printer is a black-and-white device, the default 
output method produces a single black-and-white rendition of 
each page described. 

Some printers can also be used to produce color separations. A 
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color separation consists of three or four black-and-white com¬ 
ponent pages for each color page to be described, with each 
black-and-white page corresponding to the output for one color 
component. Separations are normally prepared for use in a sub¬ 
sequent printing process in which a single page is overprinted 
three or four times to form the intended full-color output, each 
time using a different black-and-white component page and the 
ink color associated with it. 


4 OPERATORS 

The following pages contain an alphabetical listing of the new 
PostScript color operators. 
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colorimage width height bits/component matrix proc 0 [...proc n00(0rs _ 1 ] multiproc 
ncolors colorimage - 

renders a sampled image on the current page. The samples can 
contain one, three, or four color components. The first four argu¬ 
ments are the same as those for the image operator. The 
bits/component argument applies equally to all color com¬ 
ponents. colorimage permits its proc i arguments to return RGB 
or CMYK sample values rather than the single-color (gray) 
values returned by the proc argument of the image operator. 

The ncolors argument (1, 3, or 4) is the number of color com¬ 
ponents represented in the samples. If ncolors is 1, the samples 
have only one component, a gray component, and the operation 
of colorimage is equivalent to that of image with the same five 
initial arguments. If the ncolors argument is 3, the colorimage 
operator takes RGB (light-high) samples. If the ncolors argu¬ 
ment is 4, the colorimage operator takes CMYK (dark-high) 
samples. On a four-color (CMYK) machine, the PostScript inter¬ 
preter converts a three-color (RGB) image to CMYK using the 
black generation and undercolor removal procedures; a four- 
color (CMYK) image bypasses these operations. 

The multiproc argument is a boolean that distinguishes between 
two forms of the colorimage operator: false indicates the single¬ 
procedure form, which requires one procedure argument (procf)\ 
true indicates the multiple-procedure form, which requires one 
procedure argument per sample color (proc 0 ... P r °c nco i ors -\) — 
three procedure arguments for RGB samples or four-procedure 
arguments for CMYK samples. If the ncolors argument is 1, 
there is only one procedure argument, proc Q , regardless of the 
value of the multiproc argument. For a detailed description of the 
data formats and how the proc i procedures are called, see ‘ ‘Data 
formats for colorimage operator” on page 8. 

Use of setcolorscreen, setcolortransfer, setscreen, or 
settransfer by any of the proc i procedures causes unpredictable 
results. Use of the colorimage operator after a setcachedevice 
within the context of a BuildChar procedure is not permitted (an 
undefined error results). 

ERRORS: 

limitcheck, rangecheck, stackunderflow, typecheck, 
undefined, undefinedresult 
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currentblackgeneration 


currentcmykcolor 


currentcolorscreen 


- currentblackgeneration proc 

returns the current black generation function in the graphics state 
(see setblackgeneration). 

ERRORS: 

stackoverflow 


- currentcmykcolor cyan magenta yellow black 

returns the four components of the current color in the graphics 
state according to the cyan-magenta-yellow-black color model 
(see setcmykcolor). 

Note that the currentgray operator returns a weighted average 
of all four color components. Applying it is the equivalent of the 
following use of currentcmykcolor: 

1.0 currentcmykcolor 4 1 roll 0.11 mul 3 1 roll 0.59 mul 
exch 0.30 mul add add add sub dup 0.0 It {pop 0.0} if 

ERRORS: 

stackoverflow 


- currentcolorscreen r/c-frequency r/c-angle r/c-proc g/m-frequency 
g/m-angle g/m-proc b/y-frequency b/y-angle b/y-proc g/k-frequency 
g/k-angle g/k-proc 

returns all 12 current halftone screen parameters in the graphics 
state (see setcolorscreen). In the notation used here and in 
setcolorscreen, r/c is red/cyan, g/m is green/magenta, b/y is 
blue/yellow, and g/k is gray/black. 

The currentcolorscreen operator is the logical expansion of 
currentscreen to four color components. Applying the 
currentscreen operator returns the three parameters describing 
the gray/black screen. It is the equivalent of the following use of 
currentcolorscreen: 

currentcolorscreen 12 3 roll 9 {pop} repeat 

ERRORS: 

stackoverflow 
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currentcolortransfer 


currentundercolorremoval 


- currentcolortransfer redproc greenproc blueproc grayproc 

returns the current transfer functions in the graphics state for 
each of the four color components (see setcolortransfer). 

The currentcolortransfer operator is the logical expansion of 
currenttransfer to four color components. Applying the 
currenttransfer operator returns the gray transfer function. It is 
the equivalent of the following use of currentcolortransfer: 

currentcolortransfer 4 1 roll pop pop pop 

ERRORS: 

stackoverflow 


- currentundercolorremoval proc 

returns the current undercolor removal function in the graphics 
state (see setundercolorremoval). 

errors: 

stackoverflow 
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setblackgeneration proc setblackgeneration - 


sets the current black generation function parameter in the 
graphics state. The proc operand must be a PostScript language 
procedure that can be called with a number in the range 0.0 to 
1.0 (inclusive) on the operand stack and that returns a number in 
the same range. This procedure maps the minimum of the user 
cyan, magenta, and yellow color components to user black 
values. 

For additional information, see Section 3.2. 

EXAMPLE: 

{dup .75 le {pop 0.0} {.75 sub 4.0 mul} ifelse} setblackgeneration 

This PostScript language code fragment sets the black component to 
zero when the minimum of cyan, magenta, and yellow is less than or 
equal to .75. Minima greater than .75 produce a black component that 
increases linearly from 0.0 (at a minimum of .75) to 1.0 (when user 
cyan, magenta, and yellow all have values of 1.0). 

The use of setblackgeneration after a setcachedevice operation 
within the scope of a BuildChar procedure is not permitted (an 
undefined error results). 

ERRORS: 

stackunderflow, typecheck 
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setcmykcolor cyan magenta yellow black setcmykcolor - 


sets the current color parameter in the graphics state to a color 
described by the parameters cyan, magenta, yellow, and black, 
each of which must be a number in the range 0.0 to 1.0 inclusive. 
This establishes the color used subsequently to paint shapes such 
as lines, areas, and characters on the current page. This operator 
bypasses the black generation and undercolor removal opera¬ 
tions. 

For additional information, see Section 3.3. 

Note that applying the setgray operator sets the gray color com¬ 
ponent to its single argument value and the red, green, and blue 
color components to 1.0. It is the equivalent of the following use 
of setcmykcolor: 

0.0 0.0 0.0 1.0 5 -1 roll sub setcmykcolor 

The use of setcmykcolor after a setcachedeviceoperation within 
the scope of a BuildChar procedure is not permitted (an 
undefined error results). 

ERRORS: 

stackunderflow, typecheck 
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setcolorscreen r/c-frequency r/c-angle r/c-proc g/m-frequency g/m-angle g/m-proc 
b/y-frequency b/y-angle b/y-proc g/k-frequency g/k-angle g/k-proc 

setcolorscreen - 

sets the current halftone screen definitions for red/cyan (r/c), 
green/magenta (g/m), blue/yellow (b/y), and gray/black (g/k) 
output color components in the graphics state. Each of the 
r/c-frequency, g/m-frequency, b/y-frequency, and g/k-frequency 
operands is a number that specifies the screen frequency for one 
output color component, measured in halftone cells per inch in 
device space. The r/c-angle, g/m-angle, b/y-angle, and g/k-angle 
operands specify the number of degrees by which their respec¬ 
tive halftone screens are rotated with respect to the device coor¬ 
dinate system. Each of the r/c-proc, g/m-proc, b/y-proc, and 
g/k-proc operands is a PostScript language procedure (as for 
setscreen). Each procedure defines one color component’s spot 
function. (For more information on spot functions, see the sec¬ 
tion on halftone screens in the PostScript Language Reference 
Manual.) The red/cyan, green/magenta, and blue/yellow screens 
have no effect on a black-and-white device, the gray/black 
screen has no effect on an RGB or CMY device, and no screens 
have any effect on a full (8-bits-per-pixel) grayscale device. 

Color printers that use halftoning may require a different angle 
for each color component in order to produce attractive output. 
Each color printer containing a PostScript interpreter has a 
default color screen chosen to look good on that printer. 

The setcolorscreen operator is the logical expansion of 
setscreen to four color components. It takes the same three types 
of arguments as setscreen, but repeated four times. Applying the 
setscreen operator in an environment with four color com¬ 
ponents sets all four screens equally. It is the equivalent of the 
following use of setcolorscreen: 

3 copy 6 copy setcolorscreen 

EXAMPLE: 

% 50 line dot screen with 75 degree cyan, 

% 15 degree magenta, 

% 0 degree yellow, and 45 degree black angled screens, 

% which are standard for color printing 

/sfreq 50 def % 50 halftone cells per inch 

/sproc {dup mul exch dup mul add 1 exch sub} def 
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% dot-screen spot function 

sfreq 75 /sproc load % 75 degree red (cyan) screen 

sfreq 15 /sproc load % 15 degree green (magenta) screen 

sfreq 0 /sproc load % 0 degree blue (yellow) screen 
sfreq 45 /sproc load % 45 degree gray (black) screen 
setcolorscreen 

ERRORS: 

limitcheck, rangecheck, stackunderflow, typecheck 
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setcolortransfer redproc greenproc blueproc grayproc setcolortransfer - 

sets the current transfer function parameters for red, green, blue, 
and gray in the graphics state. Each operand must be a PostScript 
language procedure that may be called with a number in the 
range 0.0 to 1.0 (inclusive) on the operand stack and that will 
return a number in the same range. These procedures map user 
values of the color components (that is, those specified by 
setrgbcolor and adjusted by setblackgeneration and 
setundercolorremoval, or 1.0 minus those specified by 
setcmykcolor) to device color components (for halftones, a 
weighted average of the lightness of pixels in a halftone cell). 
Only those transfer functions corresponding to color components 
supported by a device will have an effect on that device’s output. 
For example, redproc, greenproc, and blueproc will have no ef¬ 
fect on a black-and-white device, while grayproc will have no 
effect on an RGB device. 

The single-color settransfer operator takes a single procedure 
argument whose purpose is to provide correction for a printer’s 
halftoning response. This operator is useful for a variety of ef¬ 
fects beyond its original intention as a gray response correction 
function, but it is useful only in the context of a single output 
color, as on black-and-white printers. The setcolortransfer 
operator is the logical expansion of settransfer to four color 
components; it takes four function arguments, each similar in 
purpose to the function argument of settransfer, but each func¬ 
tion separately controls the response for each of the red (1.0 
minus cyan), green (1.0 minus magenta), blue (1.0 minus 
yellow) and gray (1.0 minus black) components, respectively. 

Applying the settransfer operator sets all four transfer functions 
equally. It is the equivalent of the following use of 
setcolortransfer; 

dup dup dup setcolortransfer 

EXAMPLE: 

{} {} {dup mul} {} setcolortransfer 

This PostScript language code fragment sets device blue as the square 
of user blue and leaves the other color components unchanged. 

Calling settransfer with the argument 
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{1 exch sub} 


setundercolorremoval 


to invert an output image is not guaranteed to work if any of the 
following operators are used in generating the image: 
colorimage, setcmykcolor, setcolortransfer, sethsbcolor, and 
setrgbcolor. In the case of a device with four color components, 
inversion can be more complicated than merely inverting all of 
the components. 

The use of setcolortransfer after a setcachedevice operation 
within the scope of a BuildChar procedure is not permitted (an 
undefined error results). 

ERRORS: 

stackunderflow, typecheck 


proc setundercolorremoval - 

sets the current undercolor removal function parameter in the 
graphics state. The proc operand must be a PostScript language 
procedure that can be called with a number in the range 0.0 to 
1.0 (inclusive) on the operand stack and that will return a number 
in the range -1.0 (to increase the color components) to +1.0 (to 
decrease the color components). This procedure maps the min¬ 
imum of the cyn u , mag u , and yel u color components to a value to 
be subtracted from each of these same components. 

For additional information, see Section 3.2. 

EXAMPLE: 

{currentblackgeneration exec .5 mul} setundercolorremoval 

This PostScript language code fragment sets the undercolor removal to 
half the value of the black component from black generation. 

The use of setundercolorremoval after a setcachedevice opera¬ 
tion within the scope of a BuildChar procedure is not permitted 
(an undefined error results). 

ERRORS: 

stackunderflow, typecheck 
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A CHANGES SINCE LAST PUBLICATION OF THIS DOCUMENT 


Changes to PostScript Language Color Extensions from the 
document dated October 25, 1989, are noted in the paragraphs 
below. 

The formulas used in black generation and undercolor removal 
are more clearly explained. 

Minor amplifications and corrections have been made. 

The index has been enhanced. 

Changes to PostScript Language Color Extensions from the 
document dated October 7, 1988, are noted in the paragraphs 
below. 

The introduction has been reorganized. 

Minor amplifications and corrections have been made. 
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1 INTRODUCTION 


This document describes extensions to the PostScript® lan¬ 
guage that provide two new features: the ability to specify two 
sets of character metrics (writing directions) for a character, and 
the ability to build hierarchical composite fonts from normal 
(base) fonts. This document is intended as an extension of the 
PostScript Language Reference Manual. A more detailed dis¬ 
cussion of base fonts and the font machinery of the PostScript 
language is contained therein. 


2 FONT EXTENSIONS 


Character metrics are used during show operations to specify 
where a character shape will be placed relative to the current 
point, and how the current point will change after the character 
has been placed. Two sets of metrics are associated with a char¬ 
acter to allow for two distinct writing modes. Each set specifies a 
character origin and a width vector. The following set of 
diagrams illustrates the relationship between the two sets of 
metrics. 

Origin 1 Origin 1 


ur 




Writing Mode 1 Writing Mode 0 


The left diagram illustrates the character metrics associated with 
writing mode 0. The coordinates ll and ur specify the bounding 
box of the character relative to origin 0. wO is the character width 
vector which specifies how the current point is changed after the 






character is imaged. The center diagram represents writing mode 
1 in which wl represents the character width vector. In the last 
diagram, v is the vector from origin 0 to origin 1 and allows the 
character bounding box defined in origin 0 coordinates to be re¬ 
lated to origin 1. 

Base Fonts 

All fonts in the standard PostScript language are considered 
base fonts. Base fonts contain character descriptions that are 
used during show operations. The following entries are required 
to be in a base font dictionary (this information parallels infor¬ 
mation in the POSTSCRIPT Language Reference Manual ): 

Encoding This is an array with 256 elements; normally 
these entries are names. The Encoding array 
provides a mapping from character codes 
(indices into the array) to the names that are 
used to identify glyphs (the values in the array). 

FontType This is an integer that indicates how the char¬ 
acter descriptions are represented. A value of 3 
indicates a user-defined font; a value of 0 iden¬ 
tifies a composite font (see next section). Other 
values indicate Adobe proprietary format or are 
undefined. 

FontMatrix This is a 6 element array. It is the transformation 
matrix that transforms the character coordinate 
system used while characters are being built into 
the user coordinate system. When a font is 
modified by the scalefont or makefont 
operators, a copy of the font is created with a 
modified FontMatrix. 

Depending on the FontType, several more fields may be present 
in the font dictionary. The following entries play a role in the 
font mechanisms of the POSTSCRIPT interpreter: 

BuildChar User-defined fonts require a BuildChar proce¬ 
dure. When the POSTSCRIPT interpreter tries to 
print a character, it first looks to see if it has a 
representation of the character in the font cache. 
If not, it calls the BuildChar procedure to image 
the character. Depending on several factors, the 
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CharStrings 


Metrics 


Metrics2 


CDevProc 


interpreter may subsequently save the represen¬ 
tation in the font cache. 

The BuildChar procedure is called with the cur¬ 
rent font dictionary and the character code on 
the operand stack. Before executing any 
graphics operators the procedure must call 
setcharwidth, setcachedevice, or 

setcachedevice2 in order to pass font metric in¬ 
formation to the interpreter’s font machinery. 
Thereafter it can use most of the imaging 
operators for creating the representation. 

This is a dictionary which is needed by 
FontTypes 5 and 6. It associates a character 
name with the glyph descriptions, represented in 
a protected, proprietary form. 

This is a dictionary that is optional. If present, it 
contains information about writing direction 0. 
The keys in the dictionary are the names of 
characters. The values of a key may take several 
forms: 

• a single number, indicating a new x character 
width only (the y values are zero); 

• an array of two numbers, indicating a new left 
sidebearing (distance from the character’s 
origin to the left edge of the character bound¬ 
ing box) and new x width (the y values are 
zero). 

• an array of four numbers, indicating true vec¬ 
tors (both x and y components) for the left 
side bearing and width. 

This is a dictionary that is optional. If present, it 
contains information about writing direction 1. 
The keys in the dictionary are the names of 
characters. The value of a key is an array with 4 
elements, which specifies new values for wl and 
v. These values override the values for this infor¬ 
mation that otherwise would be used during 
character building. 

This is a procedure that is optional. If present, 
CDevProc is called after metrics information 
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has been extracted from the character descrip¬ 
tion and from the Metrics and Metrics2 diction¬ 
aries, but immediately before the font machinery 
makes an internal call to setcachedevice2. 
Eleven parameters are on the stack; they are the 
ten parameters that are to be passed to 
setcachedevice2, together with the character 
name. On return there should be ten values, 
which are then passed to setcachedevice2. 

The Metrics and Metrics2 dictionaries allow 
modification of individual character metrics in a 
given font. The CDevProc procedure allows 
global changes to a font’s metrics to be derived 
from the built-in metric data. 

WMode This is an integer that indicates which of the two 
sets of character metrics will be used when 
characters are shown from the font. For most 
fonts, a value of 0 indicates a horizontal writing 
mode, and 1 indicates a vertical writing mode. 

A base font dictionary should be large enough to have one addi¬ 
tional entry, the FID, added to it during a definefont operation. 

Composite Fonts 

Composite fonts are a collection of base fonts which are or¬ 
ganized in a hierarchical fashion. The font at the top level of the 
hierarchy is the root font. Those fonts at a lower level of the 
hierarchy are called descendent fonts. Composite fonts are 
defined with an algorithm to map show strings into characters 
that are selected from descendent base fonts. This organization 
allows for a large number of distinct characters to be selected 
from any given show string. The following entries are required 
in a composite font dictionary: 

Encoding This is an array of integers. During a show 
operation the font number that the mapping al¬ 
gorithm extracts from the show string is used to 
index into this array. The integer found there is 
then used as an index to extract a font dictionary 
from the FDepVector array (see below). 

FontType An integer value of 0 identifies the font as a 
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composite font. Any other value indicates a base 
font. 

This is an integer that indicates which mapping 
algorithm will be used to interpret the sequence 
of bytes in a show string. The mapping algo¬ 
rithm successively determines a font number and 
a character code from the show string. The font 
number is used as an index into the Encoding 
array, and the character code is used to select a 
character. 

Currently, the following mapping algorithms are 
provided: 

2 Two bytes are extracted from the show string. 
The most significant 8 bits are the font num¬ 
ber and the other 8 bits are the character code. 
This is referred to as the ‘8/8 mapping’. 

3 A byte is extracted from the show string. If it 
is equal to the escape character (see below), 
the next byte is the font number, and sub¬ 
sequent bytes are character codes for this 
font. If the first byte of a show string is not an 
escape code, font 0 is selected. 

4 A byte is extracted from the show string. The 
most significant bit is the font number, and 
the remaining 7 bits are the character code. 
This is referred to as the ‘1/7 mapping’. 

5 Two bytes are extracted from the show string. 
The most significant 9 bits are the font num¬ 
ber, and the remaining 7 bits are the character 
code. This is referred to as the ‘9/7 mapping’. 

6 The SubsVector string is used to fully 
specify this mapping type. The number of 
bytes extracted from the show string is deter¬ 
mined by the value of the first byte of the 
SubsVector string: a 0 causes one byte to be 
extracted, a 1 causes two bytes to be ex¬ 
tracted, a 2 causes three bytes to be extracted, 
and so on. The remaining values of the 
SubsVector string define a series of consecu¬ 
tive numeric ranges (see the section below on 
the SubsVector string for this definition). 
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The value extracted from the show string is 
mapped into a font number and character 
code as follows: the font number is the num¬ 
ber of the numeric range into which the ex¬ 
tracted value falls; the character code is the 
result of subtracting the minimum value con¬ 
tained in that range from the extracted value. 
This is refered to as the ‘SubsVector 
mapping’. 

If the mapping of any string passed to a show 
operator is incomplete, a rangecheck error 
results. 

FontMatrix This plays the same role in a composite font as it 
does in a base font. 

FDepVector This is an array of font dictionaries. The integer 
that is extracted from the Encoding array is used 
to index into the FDepVector to extract a font 
dictionary. If this font is a base font, then a char¬ 
acter will be extracted from it. If it is a com¬ 
posite font, then that font’s mapping algorithm is 
executed, as described in the next section. 

The following entries are not required, though they will occur in 

most composite font dictionaries. 

WMode WMode is an integer with values 0 or 1 and in¬ 

dicates which of the two sets of character 
metrics will be used when characters from the 
base fonts are shown. If it is omitted, writing 
mode 0 will be used. The writing mode of the 
root composite font overrides the writing modes 
of all its descendents. This allows a given base 
font to be used with many composite fonts, 
some of which use writing mode 0 and some of 
which use writing mode 1. 

PrefEnc This is an array that is usually the same as one or 
more of the Encoding arrays of the descendent 
fonts. Characters from descendent fonts for 
which the PrefEnc of the parent is the same as 
the Encoding of the descendent font will show 
more quickly. If this entry is not present, a null 
entry will be created by definefont. 
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The following entry is required only for composite fonts with an 
FMapType of 3. 

EscChar This is an integer that indicates the escape code 
value that is used in mapping type 3 fonts. If it is 
not present, an EscChar value of 8#377 is added 
to the dictionary by definefont. 

The following entry is required only for composite fonts with an 
FMapType of 6. 

SubsVector This is a string which controls the mapping algo¬ 
rithm for composite fonts with an FMapType of 
6. The first byte of the SubsVector string 
specifies the number of bytes to be extracted 
from the show string for each operation of the 
mapping algorithm. A value of 0 causes one byte 
to be extracted; a value of 1 causes two bytes to 
be extracted from the show string, and so on. 
The remaining bytes in the SubsVector string 
define a series of consecutive numeric ranges. 
Range 0 starts with a value of 0 and contains i 
values, where i is the first value extracted from 
the SubsVector string. The number of bytes ex¬ 
tracted from the SubsVector string to specify i 
is the same as the number of bytes extracted 
from the show string. The first value extracted 
starts at the second byte in the SubsVector 
string. Each successive number extracted from 
the SubsVector string specifies the number of 
values in the corresponding range. For example, 
a value of 1 in the first byte of the SubsVector 
string means that the number of values in range 
0 is contained in bytes two and three, the num¬ 
ber of values in range 1 is contained in bytes 
four and five, and so on. If the SubsVector 
string is not present in a font with an 
FMapType of 6, definefont results in an 
invalidfont error. 

A composite font dictionary should be large enough to have 
three additional entries, the FID, MIDVector and CurMID, 
added to it during a definefont operation. These entries serve in¬ 
ternal purposes in the font machinery. In addition, a PrefEnc 
entry will be added if one is not already there, and escape map- 
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ping fonts will have an EscChar entry added if it is not already 
present. 

Nested Composite Fonts 

The descendent fonts of a composite font may themselves be 
composite fonts. Arbitrary nesting is allowed with only two 
restrictions. The parent font of a font with escape code mapping 
must be another font with escape code mapping. In addition, the 
maximum depth of nesting is 5 levels. The mapping algorithms 
also nest according to the following rules: 

1. If the descendent font that is selected by an 8/8, 1/7, 9/7, or 
SubsVector mapping is itself a composite font, the second 
part of the value extracted from the show string is reused as 
the first part during the descendent’s mapping algorithm. 

2. If the descendent font that is selected uses escape code 
mapping, the EscChar of the root font overrides the 
EscChar of the selected font. 

3. An escape code followed by a byte that is not an escape 
code causes the mapping algorithm to descend the tree of 
fonts toward base fonts. An escape code followed by 
another escape code causes the algorithm to ascend the tree 
of fonts up toward the root font. 
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setcachedevice2 


New Operators 

wO x wO y ll x ll y ur x ur y w1 x w1 y v x v y setcachedevice2 - 

passes character metrics to the font machinery and may be executed 
only from within the context of the BuildChar procedure for a user 
defined font. wOx and wOy are the distances from the current point to 
the new current point when showing text in writing mode 0. ll x >ll y and 
ur^ury are the distances from origin 0 to the lower left and upper right 
comers of the character bounding box. wl x , wl y are the distances from 
the current point to the new current point when showing text in writing 
mode 1. v x and v y are the distances from origin 0 to origin 7. 

Two sets of metrics are installed in the character representation. They 
are used as follows. Assume that the base font is a descendent font of 
two composite fonts with different writing modes. When this character 
is shown from the composite font that has writing mode 0, the first set 
of metrics will be used. When the character is shown from the com¬ 
posite font with writing mode 7, the second set of metrics will be used. 

ERRORS: 

stackunderflow, typecheck, undefined 
SEE ALSO: 

setcachedevice, setcharwidth, setcachelimit, cachestatus 
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cshow proc string cshow - 


invokes proc once for each operation of the font mapping algorithm. 
The value of currentfont during the execution of proc is the base font 
that the algorithm ultimately selects and the current point is the position 
where the character would be imaged. When proc is invoked, the stack 
contains three values: the selected character as an integer value, and the 
x and y components of the width vector for the character in the user 
coordinate system, cshow does not image the character and does not 
change the current point (although proc may do so). When proc com¬ 
pletes execution, the value of currentfont is restored. 

cshow may be used to provide careful positioning of individual charac¬ 
ters while taking advantage of the composite font mapping machinery 
of the interpreter. 

cshow may also be used with a base font. The mapping algorithm for a 
base font simply selects consecutive characters from a show string. 

ERRORS: 

invalidfont, stackunderflow, rangecheck, typecheck 
SEE ALSO: 

show, ashow, awidthshow, widthshow, kshow 


rootfont - rootfont font 

returns the root composite font which has been selected by setfont. 
This includes invocations inside a BuildChar and cshow outcall when 
the currentfont will be a descendent base font. 

ERRORS: 

stackoverflow 

SEE ALSO: 
setfont, currentfont 


10 


Composite Font Extensions 



findencoding key findencoding array 


currentfont 


obtains an encoding array identified by the specified key and pushes it 
onto the operand stack. In some environments, findencoding may at¬ 
tempt to read an encoding array definition from a file and execute it. If 
the encoding array specified by key does not exist or cannot be found, 
findencoding executes the undefined error. 

ERRORS: 

stackunderflow, undefined, typecheck 

SEE ALSO: 
findfont 

Modified Operators 

The definefont, findfont, and setfont operators work the same 
way for both base fonts and composite fonts. The scalefont and 
makefont operators apply their transformation to each of the de¬ 
scended fonts of a descended font. The operators show, ashow, 
stringwidth, and charpath invoke the mapping algorithm when 
used with composite fonts (and a rangecheck error will result if 
the mapping of any string is incomplete), otherwise their action 
is as described in the POSTSCRIPT Language Reference Manual. 

The following operators work unchanged for base fonts; the 
description is the additional specification for composite fonts. 


- currentfont font 

returns the root composite font which has been selected by setfont 
when used outside a BuildChar and cshow outcall. When invoked 
inside a BuildChar and cshow outcall, it gives the selected base font. 

ERRORS: 

stackoverflow 

SEE ALSO: 
setfont, rootfont 
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widthshow c x c y char string widthshow - 

shows the text in string using the font mapping algorithm. In addition, 
if the integer value of the character being shown (as calculated below) 
matches char , c x and c y are added to the current point after showing the 
character. 

The font number,/, and character code, c, that are selected by the font 
mapping algorithm are combined into a single integer number accord¬ 
ing to the FMapType of the immediate parent of the selected base font 
as follows: 

2 The integer value is (fx 256) + c. 

3 The integer value is (fx 256) + c. 

4 The integer value is (fx 128) + c. 

5 The integer value is (fx 128) + c. 

6 The integer value is (fx 256) + c. 

ERRORS: 

invalidfont, nocurrentpoint, stackunderflow, rangecheck, 
typecheck 

SEE ALSO: 

show, ashow, awidthshow, cshow, stringwidth 


awidthshow c x c y char a x a y string awidthshow - 

shows the text in string using the font mapping algorithm and adds 
widths a x and a y to the current point after imaging each character. In 
addition, if the integer value of the character being shown (as cal¬ 
culated above) matches char , c x and c y are added to the current point 
after showing that character. 

ERRORS: 

invalidfont, nocurrentpoint, stackunderflow, rangecheck, 
typecheck 

SEE ALSO: 

show, ashow, cshow, kshow, widthshow, stringwidth 


kshow kshow 

gives invalidfont with a composite font. 

ERRORS: 

invalidfont 
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setcachedevice wO x wO y ll x ll y ur x ur y setcachedevice - 


passes width and bounding box information to the font machinery and 
may be executed only from within the context of the BuildChar proce¬ 
dure for a user defined font, setcachedevice installs two sets of char¬ 
acter metrics which are identical, so that characters will be positioned 
relative to the current point and change the current point in the same 
way, irrespective of the writing mode. 

ERRORS: 

stackunderflow, typecheck, undefined 
SEE ALSO: 

setcachedevice2, setcharwidth, setcachelimit, cachestatus 
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1 INTRODUCTION 


This manual describes a number of extensions to the PostScript® 
language. These extensions are initially implemented in the Dis¬ 
play PostScript® system. However, the utility of most of the ex¬ 
tensions is not limited to display applications; we anticipate that 
those extensions will eventually be incorporated into printer 
products as well. 

As a matter of policy, we do not refer to a ‘Display PostScript 
language’. There is only one PostScript language, which evolves 
over time to encompass a wider variety of device technologies, 
environments, and applications. The new facilities described in 
this manual constitute a set of extensions to the existing 
PostScript language. Considerable effort has gone into making 
these extensions upward-compatible from the existing language 
and integrating them with the PostScript language and imaging 
models in a harmonious way. We intend that a majority of these 
extensions will ultimately become a standard part of the lan¬ 
guage. 

Most of the extensions fall into a few major categories: 

• The language model is enhanced in several ways. Memory 
management is more flexible to accommodate applications 
whose resource requirements are dynamic and unpredict¬ 
able. Multiple PostScript execution contexts can execute 
simultaneously on behalf of separate applications sharing a 
single display system. There are alternative external encod¬ 
ings of the language for greater efficiency of generation 
and interpretation. 

• The set of built-in imaging operations is considerably ex¬ 
panded, though the basic imaging model is unchanged. 
Operations that are performed frequently by most applica¬ 
tions are streamlined to provide convenient generation and 
highly optimized execution. Although these extensions are 
motivated by the needs of display-based applications, their 
utility is not limited to those applications. 

• Additional extensions are included to serve the special 
needs of computer display systems. These extensions adapt 
the PostScript imaging model to the interactive, dynamic 
display environment presented by an underlying window 



system. Some extensions are generic and apply to all en¬ 
vironments; those are described in this manual. Others are 
specialized to a particular environment or a particular in¬ 
tegration of the Display PostScript system with a window 
system; those are described in documentation provided by 
the window system developer. 

Conceptual and descriptive information regarding the various 
types of extensions is presented in Sections 2 through 15, 
roughly in the above order. Individual operator descriptions are 
listed alphabetically in Section 16. Although we attempt to give 
a rationale for each extension individually, appreciating the full 
purpose of the extensions as a whole requires an overall under¬ 
standing of the Display PostScript system and the environments 
in which it is designed to operate. This topic is discussed in 
Perspective for Software Developers-, see also its list of manuals 
that document the Display PostScript system. 

A majority of the extensions can be implemented in terms of the 
existing PostScript language, though not necessarily with great 
efficiency. Through such emulation, we can provide backward 
compatibility between applications that use the extensions and 
existing PostScript language implementations that do not support 
them directly. A few extensions are unique to display applica¬ 
tions and are not relevant to printing applications; those, ob¬ 
viously, cannot be emulated. 

Other extensions 

The PostScript language has already received one major exten¬ 
sion, which has appeared in all printers with PostScript inter¬ 
preter versions 25.0 and greater. This extension was not docu¬ 
mented in the original edition of PostScript Language Reference 
Manual, but it is in editions copyright 1986 or later, as well as in 
Appendix B of this manual. 

In order to deal with color output devices, several new operators 
have been defined. Most of these operators provide control over 
various aspects of the color rendering process, including color 
halftoning and undercolor removal. (The halftone dictionary ex¬ 
tension, described in this manual, encompasses the functions of 
some of those operators.) Additionally, there is a colorimage 
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operator for rendering color sampled images. See PostScript 
Language Color Extensions for detailed information. 


2 ALTERNATIVE LANGUAGE ENCODINGS 

The standard PostScript language is based on the printable subset 
of the ASCII character set, as described in Section 3.3 of the 
PostScript Language Reference Manual. This representation is 
highly portable; it is easy to transmit and to store in a wide 
variety of operating system and communications environments. 
We refer to this representation as the ascii encoding of the 
PostScript language. 

Although it is portable, the ASCII encoding of the language is not 
particularly compact, nor is it efficient to generate and to inter¬ 
pret. In environments served by the Display PostScript system, 
there is a much closer coupling between the producer and the 
consumer of PostScript language programs than is typical when 
sending page descriptions to a printer. The application program 
and the PostScript interpreter communicate in real time; usually 
they are either in the same machine or are connected by a high- 
performance communication system. In such environments, 
compactness or efficiency are more important than maximum 
portability. 

Binary encodings 

The Display PostScript system supports two additional encod¬ 
ings of the PostScript language: the binary token encoding and 
the binary object sequence encoding. These encodings are exten¬ 
sions to the syntax of the language; that is, they provide different 
ways to express programs, but they introduce no new semantics. 
The PostScript language scanner (see PostScript Language Ref¬ 
erence Manual, Section 3.3) has been extended to recognize the 
binary encodings in addition to the existing ASCII encoding. 

The ASCII and binary encodings can be freely intermixed in any 
program; the scanner produces the same sequence of objects for 
a given program, regardless of how the program is encoded. It 
should be straightforward to translate from one encoding of the 
language to another. 
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The binary encodings are intended exclusively for machine 
generation; it is unreasonable for a human programmer to deal 
with them. Furthermore, applications using the Display 
PostScript system are encouraged to make use of the Client 
Library, a procedural interface to capabilities of the PostScript 
language, and pswrap, a translator for PostScript language 
program fragments. The design of the binary encodings is based 
primarily on the needs of those facilities. Most applications, 
therefore, need not be concerned with the details of these encod¬ 
ings. 

The binary token encoding represents elements of the PostScript 
language as individual syntactic entities. This encoding em¬ 
phasizes compactness over efficiency of generation or interpreta¬ 
tion. Most elements of the language, such as integers, reals, and 
operator names, are represented by fewer characters in the binary 
encoding than in the ASCII encoding. This encoding is most 
suitable for environments in which communication bandwidth or 
storage space is the scarce resource. 

The binary object sequence encoding represents a sequence of 
one or more PostScript objects as a single syntactic entity. This 
encoding is not compact, but it can be generated and interpreted 
very efficiently. Most elements of the language are in a natural 
machine representation or something very close to one. Ad¬ 
ditionally, this encoding is oriented toward sending fully or par¬ 
tially precompiled sequences of objects as opposed to ones 
generated on the fly. This organization matches that of the Client 
Library, which is the principal interface between applications 
and the Display PostScript system. It is most suitable for en¬ 
vironments in which execution costs dominate communication 
costs. 

Use of the binary encodings requires that the communication 
channel between the application and the PostScript interpreter be 
fully transparent. That is, it must be capable of carrying an ar¬ 
bitrary sequence of arbitrary 8-bit character codes, with no 
characters reserved for communication functions, no ‘line’ or 
‘record’ length restrictions, etc. If the communication channel is 
not transparent, the ASCII encoding must be used. 

Remember that the various language encodings apply only to 
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characters consumed by the PostScript language scanner. Apply¬ 
ing exec to an executable file or string object invokes the scan¬ 
ner, as does the token operator. File operators such as read and 
readstring, however, simply read the incoming sequence of 
characters as data, not as encoded PostScript language programs. 

The first character of each token determines what encoding is to 
be used for that token. If it is in the range 128 to 159 inclusive 
(that is, one of the first 32 codes with the high-order bit set), one 
of the binary encodings is used; 1 For binary encodings, the char¬ 
acter code is treated as a token type: it determines which encod¬ 
ing is used and sometimes also specifies the type and represen¬ 
tation of the token. 

Note that the determination of encoding occurs only on the first 
character of each token (ignoring any white space that precedes 
the token). Subsequent characters are interpreted according to 
that encoding until the end of the token is reached, regardless of 
character codes. For example, a character code in the range 128 
to 159 can appear within an ASCII string literal or a comment 
(however, a binary token type character does terminate a preced¬ 
ing ASCII name or number token). Similarly, a character code 
outside the range 128 to 159 can appear within a multiple-byte 
binary encoding. 

Token type 159 is reserved for introducing tokens whose syntax 
and semantics are specific to a particular implementation of the 
PostScript interpreter (or a particular integration with a window 
system). The standard language does not specify anything about 
such tokens, even to say how long they are. 

Number representations 

Binary tokens and binary object sequences use various represen¬ 
tations for numbers. Some numbers are the values of PostScript 
number objects (integers and reals); others provide structural in¬ 
formation, such as lengths and offsets within binary object se¬ 
quences. 

1 These codes are considered to be ‘control characters’ in most standard char¬ 
acter sets, such as ISO and JIS; they do not have glyphs assigned to them and 
are therefore unlikely to be used to construct names in PostScript language 
programs. A means exists to disable interpretation of binary encodings; see die 
setobjectformat operator in Section 3. 
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Different machine architectures use different representations for 
numbers. The two most common variations are the byte order 
within multiple-byte integers and the format of real (floating¬ 
point) numbers. 

Rather than specify a single convention for representing num¬ 
bers, the language provides a choice of representations. The ap¬ 
plication program chooses whichever convention is most ap¬ 
propriate for the machine on which it is running. The PostScript 
language scanner accepts numbers conforming to any of the con¬ 
ventions, translating to its own internal representation when 
necessary. This translation is needed only when the application 
and the PostScript interpreter are running on machines with dif¬ 
ferent architectures. 

The number representation to be used is specified as part of the 
token type (the initial character of the binary token or binary 
object sequence). There are two independent choices, one for 
byte order and one for real format. The byte order choices are: 

• High-order byte first (‘big-endian’)—in a multiple-byte in¬ 
teger or fixed-point number, the high-order byte comes 
first, followed by successively lower-order bytes. 

• Low-order byte first (‘little-endian’) — in a multiple-byte 
integer or fixed-point number, the low-order byte comes 
first, followed by successively higher-order bytes. 

The real format choices are: 

• IEEE standard —a real number is represented in IEEE 32- 
bit floating-point format. 2 The order of the bytes is the 
same as the integer byte order, as specified above. For ex¬ 
ample, if the high-order byte of an integer comes first, then 
the sign and first 7 exponent bits of an IEEE standard real 
come first. 

• Native —a real is represented in the native format for the 
machine on which the PostScript interpreter is running. 
This may be a standard format or something completely 
different; the choice of byte order is not relevant. The ap¬ 
plication program is responsible for finding out what the 
correct format is. In general, this is useful only in environ- 


2 IEEE 754: Standard for Binary Floating-Point Arithmetic, 1985. 
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ments where it is known that the application and the 
PostScript interpreter are running on the same machine or 
on machines with compatible architectures. Obviously, 
PostScript language programs that use this real number rep¬ 
resentation are not portable. 

Since each binary token and binary object sequence defines its 
own number representation, binary encoded programs with dif¬ 
ferent number representations can be freely intermixed. This is a 
convenience for applications that obtain portions of PostScript 
language programs from different sources. 

Binary tokens 

Binary tokens are variable-length binary encodings of certain 
types of PostScript objects. A binary token represents an object 
that can also be represented in the ASCII encoding, but usually 
with fewer characters. Thus, the binary encoding is usually the 
most compact representation of a program, though not neces¬ 
sarily the most efficient to execute. 

Semantically, a binary token is equivalent to some corresponding 
ASCII token. When the scanner encounters the binary encoding 
for the integer 123, it produces the same result as when it en¬ 
counters an ASCII token consisting of the characters ‘123’. That 
is, it produces an integer object whose value is 123; the object is 
the same (and occupies the same amount of space if stored in 
VM) whether it came from a binary or an ASCII token. 

Unlike the ASCII and binary object sequence encodings, the bi¬ 
nary token encoding is incomplete: not everything in the lan¬ 
guage can be expressed as binary tokens. For example, it makes 
no sense to have binary token encodings of ‘{’ and “}’, since their 
ASCII encodings are already compact. Similarly, it makes no 
sense to have binary encodings for the names of operators that 
are rarely used, since their contribution to the overall length of a 
PostScript language program is negligible. The incompleteness 
of the binary token encoding is not a problem, since ASCII and 
binary tokens can be freely intermixed. 

The binary token encoding is summarized in the following table. 
A binary token begins with a token type character, as discussed 
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earlier. A majority of the token types (128 to 159) are used for 
binary tokens; the remainder are used for binary object se¬ 
quences or are unassigned. The token type determines how many 
additional characters comprise the token and how the token is 
interpreted. 


Token Additional Interpretation 

type(s) characters 


128 - 131 - binary object sequence; this encoding is described in the next section. 


132 

4 

32-bit integer, high-order byte first. 

133 

4 

32-bit integer, low-order byte first. 

134 

2 

16-bit integer, high-order byte first. 

135 

2 

16-bit integer, low-order byte first. 

136 

1 

8-bit integer, treating the character after the token type as a signed number n ; 
-128 <n< 127. 

137 

3 or 5 

16- or 32-bit fixed-point number. The number representation (size, byte order, 
and scale) is encoded in the character immediately following the token type; 
the remaining two or four characters are the number itself. The representation 
parameter is treated as an unsigned integer r in the range 0 to 255: 



0<r<31 32-bit fixed-point number, high-order byte first; the scale 
parameter (number of bits of fraction) is equal to r. 

32 < r < 47 16-bit fixed-point number, high-order byte first; scale = r - 32. 
r > 128 same as r - 128 except that all numbers are given low-order byte 

first. 

138 

4 

32-bit IEEE standard real, high-order byte first. 

139 

4 

32-bit IEEE standard real, low-order byte first. 

140 

4 

32-bit native real. 

141 

1 

boolean. The character following the token type gives the value: 0 for false, 1 
for true. 

142 

1 + n 

string of length n. The parameter n is contained in the character after the token 
type; 0 <n< 255. The n characters of the string follow the parameter. 

143 

2 + n 

long string of length n . The 16-bit parameter n is contained in the two charac¬ 
ters after the token type, represented high-order byte first; 0 < n < 65535. The n 
characters of the string follow the parameter. 

144 

2 + n 

long string of length n. The 16-bit parameter n is contained in the two charac¬ 
ters after the token type, represented low-order byte first; 0 < n < 65535. The n 


characters of the string follow the parameter. 
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145 

1 

literal name from system name table indexed by index. The index parameter is 
contained in the character after the token type; 0 < index < 255. 

146 

1 

executable name from system name table indexed by index. The index 
parameter is contained in the character after the token type; 0 ^ index £ 255. 

147 

1 

literal name from user name table indexed by index. The index parameter is 
contained in the character after the token type; 0 < index £ 255. 

148 

1 

executable name from user name table indexed by index. The index parameter 
is contained in the character after the token type; 0 < index < 255. 

149 

3 + data 

homogeneous number array. This consists of a four-character header (including 
the token type) followed by a variable length array of numbers whose size and 
representation are specified in the header. This is described in detail below. 

150-158 

- 

unassigned; occurrence of a token with these types will cause a syntaxerror. 

159 

unspecified 

reserved for token types that are implementation or window system specific. 


The encodings for integers, reals, and booleans are straightfor¬ 
ward and require no further explanation. The other token types 
require additional discussion. 

A fixed-point number is a binary number having integer and frac¬ 
tional parts; the position of the binary point is specified by a 
separate scale value. In a fixed-point number of n bits, the high- 
order bit is the sign, the next n - scale - 1 bits are the integer 
part, and the low-order scale bits are the fractional part. For ex¬ 
ample, if the number is 16 bits wide and scale is 5, it is inter¬ 
preted as a sign, a 10-bit integer part, and a 5-bit fractional part. 
A negative number is represented in two’s complement form. 

There are both 16- and 32-bit fixed-point numbers, allowing an 
application to make a tradeoff between compactness and preci¬ 
sion. Regardless of the token’s length, the object produced by the 
scanner for a fixed-point number is an integer if scale is zero; 
otherwise it is a real. Note that a 32-bit fixed-point number ac¬ 
tually takes more characters to represent than a 32-bit real; it is 
useful only if the application already represents numbers that 
way. (Using this representation makes somewhat more sense in 
homogeneous number arrays, described below.) 

A string token specifies the string’s length as a one- or two- 
character unsigned integer. The specified number of characters 
of the string follow immediately. Note that all the characters are 
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treated literally; there is no special treatment of ‘V or other 
characters. The main purpose of the binary token encoding of 
strings is to allow arbitrary binary data to be represented 
straightforwardly, not to save space. 

The name encodings specify a system name index or a user name 
index that selects a name object from the system or user name 
table and uses it as either a literal or an executable name. This 
mechanism is described below. Note that only the first 256 ele¬ 
ments of each array can be accessed by this means. 

A homogeneous number array is a single binary token that 
represents a PostScript literal array object whose elements are all 
numbers. The token consists of a four-character header 
(including the token type) followed by a variable-length se¬ 
quence of numbers. All of the numbers are represented in one 
way, which is specified in the header. 

The header consists of the token type character (149, denoting a 
homogeneous number array), a character that describes the num¬ 
ber representation, and two characters that specify the array 
length (number of elements). The number representation is 
treated as an unsigned integer r in the range 0 to 255 and is 
interpreted as follows; 


0<r<31 


32 < r < 47 

48 

49 

128 <r< 177 


32-bit fixed-point number, high-order byte first; the scale parameter (number of 
bits of fraction) is equal to r. 

16-bit fixed-point number, high-order byte first; scale = r - 32. 

32-bit IEEE standard real, high-order byte first. 

32-bit native real. 

same as r - 128 except that all numbers are given low-order byte first. 


Note that this interpretation is similar to that of the represen¬ 
tation parameter r in individual fixed-point number tokens. 

The array’s length is given by the last two characters of the 
header, treated as an unsigned 16-bit number. The byte order in 
this field is as specified by the number representation: r < 128 
indicates high-order byte first; r > 128 indicates low-order byte 
first. 
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Following the header are 2 x length or 4 x length characters, 
depending on representation, that encode successive numbers of 
the array. 

When this class of token is consumed by the PostScript language 
scanner, it produces a literal array object. The elements of this 
array are all integers if the representation parameter r is 0, 32, 
128, or 160 (specifying fixed-point numbers with a scale of 
zero); otherwise they are all reals. Once scanned, such an array is 
indistinguishable from an array produced by other means (and 
occupies the same amount of space). 

Although the homogeneous number array representation is useful 
in its own right, it is particularly useful in conjunction with 
operators that take an encoded number string as an operand. This 
is described later in this section. 

Binary object sequences 

A binary object sequence is a single token that describes an 
executable array of objects, each of which may be a simple ob¬ 
ject, a string, or another array nested to arbitrary depth. The en¬ 
tire sequence can be constructed, transmitted, and scanned as a 
single self-contained syntactic entity. 

Semantically, a binary object sequence is an ordinary executable 
array, as if the objects in the sequence had been surrounded by 
*{’ and *}’, but with one important difference: its execution is 
immediate instead of deferred. That is, when a binary object se¬ 
quence is encountered in a file being executed directly by the 
PostScript interpreter, the interpreter performs an implicit exec 
instead of pushing the array on the operand stack as it would 
ordinarily. (This special treatment does not apply when a binary 
object sequence appears in a context where execution is already 
deferred, e.g., nested in ASCII-encoded ‘{’ and *}’ or consumed by 
the token operator.) 

Since a binary object sequence is syntactically a single token, it 
is completely processed by the scanner before any of it is ex¬ 
ecuted by the interpreter. The entire array and all its subsidiary 
composite objects are allocated in private or shared VM accord¬ 
ing to the VM allocation mode in effect at the time the binary 
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object sequence is scanned (see Section 4). Similarly, encoded 
name bindings are those in effect at scan time (see below). 

The encoding emphasizes ease of construction and interpretation 
over compactness. Each object is represented by eight successive 
characters. In the case of simple objects, these eight characters 
describe the entire object (type, attributes, and value). In the case 
of composite objects, the eight characters include a reference to 
some other part of the binary object sequence where the value of 
the object resides. The entire structure is easy to describe using 
the data type definition facilities of implementation languages 
such as C and Pascal. 

A binary object sequence consists of four parts in the following 
order: 

• header —four or eight characters of information about the 
binary object sequence as a whole; 

• top-level array —a sequence of objects, eight characters 
each, which constitute the value of the main array object; 

• subsidiary arrays —more eight-character objects, which 
constitute the values of nested array objects; 

• string values —an unstructured sequence of characters, 
which constitute the values of string objects and the text of 
name objects. 

The first character of the header is the token type, mentioned 
earlier. Four token types denote a binary object sequence and 
select a number representation for all integers and reals em¬ 
bedded within it: 

128 high-order byte first; IEEE standard real format 

129 low-order byte first; IEEE standard real format 

130 high-order byte first; native real format 

131 low-order byte first; native real format 

At this point, the header can take one of two forms, depending 
upon the number of elements in the top level array and the over¬ 
all length of the object sequence. If there are 255 top-level ele¬ 
ments or fewer and the overall length of the object sequence is 
65,535 characters or fewer, the second character specifies the 
number of elements in the top-level array and the third and 
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fourth characters, taken together as a 16-bit unsigned integer, 
specify the size in characters of the entire binary object se¬ 
quence, including header, top-level, and subsidiary arrays, and 
string values. (The order of characters that constitute this size 
field is according to the number representation specified by the 
token type. This is true of all multi-character numbers in the bi¬ 
nary object sequence.) If there are more than 255 top-level ob¬ 
jects or the overall length of the object sequence is greater than 
65,535 characters, the second character is set to zero. The next 
two bytes are the number of top-level elements and the next four 
bytes are the overall length of the object sequence (again, the 
order of characters that constitute these size fields is according to 
the number representation specified by the token type). 

Following the header is an uninterrupted sequence of eight- 
character objects that constitute both the top-level array and sub¬ 
sidiary arrays. The length of this sequence is not given explicitly; 
it continues until the earliest string value referenced from an ob¬ 
ject in the sequence, or until the end of the entire token. 

The first character of each object in the sequence gives the 
object’s literal/executable attribute in the high-order bit and its 
type in the low-order 7 bits. 3 The attribute values are: 

0 literal 

1 executable 

The meaning of the object type field is given below. 

The second character of an object is unused; its value must be 
zero. The third and fourth characters constitute a 16-bit integer, 
referred to as the length. The fifth through eighth characters con¬ 
stitute the value. The interpretation of the length and value fields 
depends on the object’s type. (Once again, the character order 
within these fields is according to the number representation for 
the binary object sequence overall.) 

The object types and the interpretation of the length and value 
fields are: 


3 Note that the positions of these fields within the character are not influenced 
by the prevailing number representation. To describe these as distinct fields in a 
C ‘struct’ requires different type definitions for big-endian and little-endian 
machines. 
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0 null: length and value are unused 

1 integer: length is unused; value is a signed 32-bit in¬ 
teger 

2 real: length is unused; value is a real 

3 name: see below 

4 boolean: length is unused; value is 0 for false, 1 for 
true 

5 string: see below 

6 immediately evaluated name: see below 
9 array: see below 

10 mark: length and value are unused 

For types string and array, the length field specifies the number 
of elements (characters in a string or objects in an array); it is 
treated as an unsigned 16-bit integer. The value field specifies 
the offset, in characters, of the start of the object’s value relative 
to the first character of the first object in the top-level array. An 
array offset must refer somewhere within the top-level or sub¬ 
sidiary arrays; it must be a multiple of 8. A string offset must 
refer somewhere within the string values; the strings have no 
alignment requirement and need not be null-terminated or other¬ 
wise delimited. (If the length of a string or array object is zero, 
its value is disregarded.) 

For the name type, the length field is treated as a signed 16-bit 
integer that selects one of three interpretations of the value field: 

n > 0 value is an offset to the text of the name, just the same 
as for a string; n is the name’s length (which must be 
within the implementation limit for names) 

0 value is a user name index (see below) 

-1 value is a system name index (see below) 

An immediately evaluated name object is analogous to the 
'llname ’ syntax of the ASCII encoding. (See Appendix B.) This 
object is treated just the same as a name, as described above. 
However, the scanner then immediately looks up the name in the 
context of the current dictionary stack and substitutes the cor¬ 
responding value for that name. If the name is not found, an 
undefined error occurs. 

For the composite objects, there are no enforced restrictions 
against multiple references to the same value or recursive or self- 
referential arrays. However, such structures cannot be expressed 
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directly in the ASCII or binary token encodings of the language; 
their use violates the interchangeability of the encodings. There¬ 
fore, the recommended structure of a binary object sequence is 
for each composite object to refer to a distinct value. There is 
one exception: references from multiple name objects to the 
same string value are specifically encouraged, since name ob¬ 
jects are unique by definition. 

The scanner will generate a syntaxerror upon encountering a 
binary object sequence that is malformed in any way. Possible 
causes include: 

• an object type that is undefined; 

• an ‘unused’ field that is not zero; 

• lengths and offsets that, in combination, would refer out¬ 
side the bounds of the binary object sequence; 

• an array offset that is not a multiple of 8 or that refers 
beyond the earliest string offset. 

As is true for all errors, when a syntaxerror occurs, the 
PostScript interpreter pushes onto the operand stack the object 
that caused the error. For an error detected by the scanner, 
however, there is not actually such an object, since the error oc¬ 
curred before the scanner had finished creating one. Instead, the 
scanner fabricates a string object consisting of the characters en¬ 
countered so far in the current token. If a binary token or binary 
object sequence was being scanned, the string object produced is 
a description of the token rather than the literal characters (which 
would be gibberish if printed as part of an error message). For 
example: 

(bin obj seq, type=128, elements=23, size=234, 
array out of bounds) 

System and user name encodings 

Both the binary token and binary object sequence encodings 
provide optional means for representing names as small integers 
instead of as full text strings. Such an integer is either a system 
name index or a user name index. Careful use of encoded names 
can result in substantial space savings and execution perfor¬ 
mance improvement. 
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A name index is a reference to an element of a name table al¬ 
ready known to the PostScript interpreter. When the scanner en¬ 
counters a name token that specifies a name index (rather than a 
text name), it immediately substitutes the corresponding element 
of the appropriate table. This substitution occurs at scan time, not 
at execution time; the result of the substitution is an ordinary 
PostScript name object. 

A system name index is an index into the system name table, 
which is built-in and has a standard value. The elements of this 
table are standard operator names, font names, character names, 
and other names that are a standard part of the PostScript VM. 
The contents of this table are documented in appendix C; they 
are also available as a machine-readable file for use by pswrap, 
translators, and other programs that deal with binary encodings. 

A user name index is an index into the user name table, whose 
contents may be defined by a PostScript language program by 
means of the defineusername operator. This provides efficient 
encodings of non-system names that are used frequently. 
However, there are various restrictions on user name encodings; 
additions to the user name table must be made in a stylized way 
to ensure correct behavior. 

If there is no name associated with a system or user name index, 
the scanner generates an undefined error; the offending com¬ 
mand is ‘systems’ or ‘usern’, where n is the decimal represen¬ 
tation of the index. 

An encoded binary name specifies (as part of the encoding) 
whether the name is to be literal or executable; this overrides the 
corresponding attribute of the replacement name object. Thus, a 
given element of the system or user name table can be treated as 
either literal or executable when referenced from a binary token 
or object sequence. In the binary object sequence encoding, one 
can also specify an immediately evaluated name object, 
analogous to 'llname'. When such an object specifies a name 
index, note that there are two substitutions: the first obtains a 
name object from the appropriate table; the second looks up that 
name object in the current dictionary context. 

One should be aware that the binary token encoding provides 
means to reference only the first 256 elements of either of the 
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name tables. (The binary object sequence encoding does not 
have this limitation.) Maximum program compactness can be 
achieved by organizing the user name table in such a way that 
the most commonly used names are in the first 256 elements. 

Like everything else having to do with binary encodings, en¬ 
coded names are intended for machine generation only. The 
pswrap and Client Library facilities are the preferred means for 
application programs to generate binary encoded programs. In 
particular, those facilities maintain the user name table automati¬ 
cally and encode names using both the system and user name 
tables. An application should not attempt to alter the user name 
table itself, since that would interfere with the activity of the 
Client Library. 

A program can depend on a given system name index represent¬ 
ing a particular name object. Applications that generate binary 
encoded PostScript language programs are encouraged to take 
advantage of system name index encodings, since they save both 
space and time. 

The meaning of a given user name index is local to a specific 
PostScript execution context—more precisely, to a context’s 
private VM or space (see Sections 4 and 5). If several contexts 
are associated with the same space, a user name index defined in 
one context may be used in another context. (It is the client’s 
responsibility to synchronize execution of the contexts so that 
definition and use occur in the correct order.) 

The user name index facility is intended for use only during in¬ 
teractive sessions with a Display PostScript system. It should not 
be used in a PostScript language program that must stand by 
itself, such as one sent to a printer or written to a file for later 
use. If a program contains user name index encodings, it cannot 
be composed with or embedded in other PostScript language 
programs and it cannot easily be translated to the ASCII encoding. 
PostScript printers may not support user definition of name en¬ 
codings. The Client Library has an option to disable use of user 
name encodings and produce text encoded names always; this 
option may be invoked dynamically by an application program 
to produce a PostScript language program that is to be captured 
in a file or diverted to a printer. 
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Encoded number strings 


Several of the new operators require as operands an indefinitely 
long sequence of numbers to be used as coordinate values (either 
absolute or relative). The operators include those dealing with 
user paths, rectangles, and explicitly positioned text, all of which 
are described in other parts of this manual. In the most common 
use of these operators, all the numbers are provided as literal 
values by the application as opposed to being computed by the 
PostScript language program. 

In order to facilitate this common use and to streamline both the 
generation and the interpretation of numeric operand sequences, 
we have defined a standard facility for presenting such operands 
to an operator. A number sequence may be represented either as 
an ordinary PostScript array object (whose elements are to be 
used successively) or as an encoded number string. 

An encoded number string is a PostScript string object that con¬ 
sists of a single homogeneous number array according to the 
binary token encoding described above. That is, the first four 
characters are treated as a header; the remaining characters are 
treated as a sequence of numbers encoded as described in the 
header. 

The attractive feature of an encoded number string is that it is a 
compact representation of a number sequence both in its external 
form and in VM. Syntactically, it is simply a string object; it 
remains in that form after being scanned and placed in VM. It is 
interpreted as a sequence of numbers only when it is actually 
used as an operand of an operator that is expecting a number 
array. Furthermore, even then it is neither processed by the scan¬ 
ner nor expanded into a PostScript array object; instead, the 
numbers are consumed directly by the operator. This arrange¬ 
ment is both compact and efficient. 

The following are equivalent ways of invoking rectfill, which is 
one of the new operators that expect number sequences as 
operands: 

[ Ascn-encoded numbers ] rectfill 
homogeneous number array rectfill 
string rectfill 
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The first line constructs an ordinary PostScript array object con¬ 
taining the numbers and passes it to rectfill. (This is actually the 
most general form, since the ‘[’ and *]’ could enclose an arbitrary 
computation that produces the numbers and pushes them on the 
stack.) 

On the second line, a binary token representing a homogeneous 
number array appears directly in the program. In this instance, 
the scanner produces an array object, which is then consumed by 
rectfill. The rectfill operator treats this case as indistinguishable 
from the first one. 

On the third line, a string object appears in the program. This 
string object is most likely encoded as a binary token or an ele¬ 
ment of a binary object sequence, but conceivably it could be an 
ASCII-encoded hexadecimal string enclosed in '<’ and V or a 
string value read by readstring. (An ordinary ASCII string 
enclosed in ‘(’ and *)’ is less suitable because of the need to 
quote special characters.) When rectfill is given a string object, 
it interprets the value of the string as the binary token encoding 
of a homogeneous number array. The result produced is equiv¬ 
alent to: 

string cvx exec rectfill 

Here, exec interprets string as a PostScript language program. 
The scanner, finding that the first (and only) token in string is a 
binary token encoding of a homogeneous number array, 
produces that array and pushes it on the operand stack. The 
rectfill now sees an array operand, as in one of the first two lines 
in the earlier example. However, although the end result is the 
same, passing string directly to rectfill is much more efficient 
(in both time and space), since it bypasses creating the array ob¬ 
ject in VM. 

The operators that use encoded number strings include rectfill, 
rectstroke, rectclip, rectviewclip, xshow, yshow, and xyshow. 
Additionally, an encoded user path represents its numeric 
operands as an encoded number string; the relevant operators are 

ufill, ueofill, uappend, inufill, inueofill, and inustroke. 
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3 STRUCTURED OUTPUT 


The Display PostScript system provides a means for a program 
to send various kinds of information back to the application (via 
the Client Library). This information includes the values of ob¬ 
jects produced by queries, error messages, unstructured text 
generated by print, and perhaps window system specific events. 
A PostScript context writes all of this data to its standard output 
file. The Client Library requires a way to distinguish among 
these different kinds of information received from a context. 

To serve this need, we have defined a structured output format 
and provided means for a PostScript language program to 
generate output conforming to it. The format is basically the 
same as the binary object sequence representation for input, 
described in Section 2. 

A program that writes structured output should be judicious in its 
use of unstructured output primitives such as print and *=’. In 
particular, since the start of a binary object sequence is indicated 
by a character whose code is in the range 128 to 159 inclusive, 
unstructured output should consist only of character codes out¬ 
side that range; otherwise, confusion will ensue in the Client 
Library or the application. (Of course, this is only a convention; 
by prior arrangement, a program may send unstructured data to 
the application.) 

The new operator printobject writes an object to the standard 
output file as a binary object sequence. A similar operator, 
writeobject, writes to a file. The binary object sequence contains 
a top-level array consisting of one element which is the object 
being written; see the description of binary object sequences in 
Section 2. That object, however, can be composite, so the binary 
object sequence may include subsidiary arrays and strings. 

In the binary object sequences produced by printobject and 
writeobject, the number representation is controlled by the 
setobjectformat operator. The binary object sequence has a 
token type that identifies the representation used. 

Accompanying the top-level object in the object sequence is a 
one-character tag, which is specified as an operand of 
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printobject. This tag is carried in the second character of the 
object, which is otherwise unused (see Section 2). Only the top- 
level object receives a tag; the second byte of subsidiary objects 
is zero. In spite of its physical position, the tag is logically asso¬ 
ciated with the object sequence as a whole. 

The purpose of the tag is to enable the PostScript language 
program to specify the intended disposition of the object se¬ 
quence. A few tag values are reserved for reporting errors (see 
below); the remaining tag values may be used arbitrarily. The 
Client Library uses tags when it issues a query to the PostScript 
context. The query consists of a PostScript language program 
that includes one or more instances of printobject to send 
responses back to the Client Library. A different tag is specified 
for each printobject so that the Client Library can distinguish 
among the responses as they arrive. 

Tag values 0 through 249 are available for general use. Tag 
values 250 through 255 are reserved to identify object sequences 
that have special significance. Of these, only tag value 250 is 
presently defined: it is used to report errors. 

Errors are initiated as described in Sections 3.6 and 3.8 of the 
PostScript Language Reference Manual. Normally when an error 
occurs, control automatically passes from the PostScript lan¬ 
guage program to an error-handling procedure in the root control 
program of the context. If binary encoding is disabled (see 
setobjectformat), the error handler generates a text message 
similar to an error message on a PostScript printer. Otherwise it 
writes a binary object sequence with a tag value of 250. 

The binary object sequence that reports an error contains a four- 
element array as its top-level object. The array elements, ordered 
as they appear, are: 

• The name ‘Error’ (indicates an ordinary error detected by 
the PostScript interpreter; a different name could indicate 
another class of errors, in which case the meanings of the 
other array elements might be different). 

• The name that identifies the specific error (e.g., 
typecheck). 

• The object that was being executed when the error oc- 
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curred; if the object that raised the error is not printable, 
some suitable substitute is provided — for example, an 
operator name in place of an operator object. 

• An error-handler flag (a boolean object whose value is true 
if the program expects to resynchronize with the client and 
false otherwise). 

The normal error handler, handleerror, sets the flag to false. An 
alternate error handler, resynchhandleerror, sets the flag to 
true ; it should be used when the program expects to 
resynchronize with the client. See the section on handling errors 
in the Client Library Reference Manual for more information on 
handleerror and resynchandleerror. 

In addition to binary object sequences and unstructured text, a 
program may need to send special tokens whose syntax and 
semantics are implementation or environment dependent. For ex¬ 
ample, if a PostScript language program is able to intercept win¬ 
dow system events, it may need to send some of those events to 
the application. Binary token type 159 is reserved for this pur¬ 
pose (see Section 2). 


4 MEMORY MANAGEMENT 

The PostScript interpreter used in printers has a very simple ap¬ 
proach to management of virtual memory (VM) resources. 
Memory consumed by creating new composite objects is simply 
not reclaimed until a restore is executed; the VM then reverts to 
the state it was in at the time of the matching save. 

This approach works well for PostScript printers. Execution of a 
PostScript page description should ordinarily have no lasting 
side effects. A page description is divided into pages; individual 
pages should have no lasting side effects that would influence 
the execution of subsequent pages. The strict nesting of VM 
states imposed by the save/restore facility matches this structure 
well. To ensure portability, PostScript language programs that 
are page descriptions should assume that VM is managed in this 
way. 

Interactive display applications, on the other hand, perform 
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operations in a much less structured fashion. The stream of 
PostScript language text generated by an application is typically 
not divided into ‘pages’ and may have no obvious overall struc¬ 
ture. Furthermore, an interactive session may never terminate; 
there is no opportunity to reclaim VM resources consumed 
during the session. Thus, save and restore are much less suitable 
for overall memory management, though they can still be useful 
for encapsulating isolated computations. 

Garbage collection 

A more sophisticated approach to memory management is 
clearly required. The Display PostScript system includes an 
automatic VM reclamation facility, popularly known as a 
‘garbage collector’. This facility automatically reclaims the 
memory occupied by composite objects that are no longer acces¬ 
sible to the PostScript language program (i.e., do not appear on 
any of the stacks or as elements of other composite objects). 

Garbage collection is not a language feature per se, since it nor¬ 
mally takes place without explicit action on the part of the 
PostScript language program being executed. However, the 
presence of a garbage collector strongly influences the style of 
programming that is permissible. A program that endlessly con¬ 
sumes VM and never executes save and restore will eventually 
encounter a VMerror if executed by a PostScript interpreter that 
does not have garbage collection. 

Of course, garbage collection is not entirely free. There is a cer¬ 
tain cost associated with creating and destroying composite ob¬ 
jects in VM. The most common case is that of literal objects 
(strings, user path procedures, etc.) that are immediately con¬ 
sumed by operators such as show and ufill and then never used 
again. The garbage collector is engineered to deal with this case 
inexpensively, so application programs should not hesitate to 
take advantage of it. However, the cost of garbage collection is 
greater for objects that have longer lifetimes or that are allocated 
explicitly. Programs that frequently require temporary objects 
are encouraged to create them once and reuse them instead of 
creating new ones on every use. 

Even with garbage collection, the save and restore operators still 
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have their standard behavior. That is, restore still resets all ob¬ 
jects visible to the PostScript language program to their state at 
the time of the matching save. It still reclaims all composite ob¬ 
jects created since the matching save (and does so very cheaply). 
Thus, a Display PostScript application may continue to use the 
save/restore facility in cases where its semantics are useful. 

In an environment with garbage collection, the semantics of 
vmstatus are not as well defined as they are in an environment 
with explicit memory management. The garbage collection 
process operates intermittently, not continously; some inacces¬ 
sible objects cannot immediately be recognized as such. Thus, 
the used value returned by this operator is only meaningful im¬ 
mediately after a garbage collection has taken place. This can be 
invoked explicitly by the vmreclaim operator. The 
setvmthreshold operator provides additional control over the 
behavior of the garbage collector. 

Deliberate discard and undef 

With garbage collection comes the opportunity to deliberately 
discard composite objects that are no longer needed and to do so 
in an order unrelated to the time of creation of those objects. 
This is particularly valuable for very large objects such as font 
definitions. In order for this to be done effectively, certain pro¬ 
gramming considerations must be observed; these considerations 
arise mainly from interactions with save and restore. 

As explained above, the VM occupied by a composite object can 
be reclaimed by the garbage collector as soon as it becomes in¬ 
accessible to the PostScript language program. For example, if 
the only reference to a particular composite object consists of an 
element of some array or dictionary, replacing that element with 
a null object (say, using put) renders the former object’s value 
inaccessible and reclaimable. 

In the case of a dictionary, it is useful to be able to remove an 
entry entirely, that is, to remove both the key and the value of a 
key-value pair, as opposed to replacing the value with some 
other value. This action is performed by the new operator undef, 
which is described below. Removing an entry from the 
FontDirectory dictionary requires another new operator, 


24 


Extensions for the Display PostScript System / Version of January 23,1990 



undefinefont, since FontDirectory is read-only except by font 
specific operators. 

Regardless of the means used to remove references to a com¬ 
posite object, the action will be undone by a subsequent restore 
if the reference existed at the time of the matching save. This is 
true even for undef: restore reinstates the deleted dictionary 
entry. In this situation, the referenced object has never become 
truly inaccessible, since access to it can be reinstated by execut¬ 
ing restore. Consequently, the VM occupied by that object is not 
reclaimed. 

As a practical matter, this means that a PostScript language 
program can successfully discard a composite object only while 
executing at the same depth of save/restore nesting as was in 
effect when the object was created. Fonts are typically defined at 
the outermost level of save/restore nesting (or in shared VM, as 
described below). To discard a font definition and reclaim the 
VM that it occupies, one must execute undefinefont at the same 
level of save/restore nesting. 

Shared VM 

The existing model of VM is that of a uniform, unstructured 
store of composite objects. This model has been extended to sup¬ 
port multiple VMs whose contents have different lifetime and 
visibility and whose behavior with respect to save and restore is 
decoupled. 

The motivation for introducing multiple VMs is the need to sup¬ 
port multiple, concurrent execution contexts in the Display 
PostScript system. The facilities that deal with multiple contexts 
are described in Section 5. However, most of the semantics of 
the multiple VM facility can be described independently of con¬ 
texts and are therefore presented here. 

Each PostScript execution context has a private VM that is 
visible only within that context. Additionally, there is a single 
shared VM that is visible to all contexts and that can be. updated 
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by any context under suitable conditions. 4 

Of all the objects visible to a PostScript language program, some 
are in private VM and some are in shared VM. New composite 
objects, whether created implicitly by the PostScript language 
scanner or explicitly by operators, are normally allocated in 
private VM. A program can read and alter the values of objects 
in private VM in the usual way, subject only to the access at¬ 
tributes of the objects involved. A program can also read the 
values of objects in shared VM without any unusual restrictions. 
Thus, for most purposes, the behavior of the two-part VM is vir¬ 
tually indistinguishable from the behavior of the conventional 
one-part VM. 

The ability to alter the values of objects in shared VM is 
restricted in one important way. 5 It is illegal to store a private 
object as an element of a shared object. More precisely, a com¬ 
posite object whose value was created by ordinary means (and is 
therefore in private VM) cannot be stored as an element of an 
existing composite object whose value is in shared VM. An at¬ 
tempt to do so will result in an invalidaccess error. On the other 
hand, there are no restrictions on storing simple objects, such as 
integers and names, as elements of shared objects; nor are there 
restrictions on storing shared objects as elements of private ob¬ 
jects. In this connection, name objects are always treated as if 
they were shared. The scheck operator inquires whether an ob¬ 
ject is private or shared. 

In order to create a new composite object in shared VM, a 
program must explicitly enter shared VM allocation mode. This 
is done by executing the setshared operator, which switches be¬ 
tween private and shared VM allocation modes. This mode con¬ 
trols the VM region in which the values of new composite ob- 

4 Even if a PostScript interpreter supports only one context, as in a printer, 
having a ‘shared’ VM is still useful. The shared VM holds objects whose 
lifetime is independent of the lifetime of objects in the (single) private VM. 
Such objects may include font definitions that are to persist through execution 
of multiple print jobs. In this respect, shared VM is a replacement for the 
cumbersome and less general exitserver mechanism. 

5 The ability to alter the shared VM may be further restricted in some environ¬ 
ments. For example, a PostScript printer may require a program to present a 
password to some statusdict operator before attempting to alter the shared VM. 
Such restrictions do not ordinarily make sense in environments served by the 
Display PostScript system. 
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jects are subsequently allocated; it affects both objects created 
implicitly by the scanner and ones created explicitly by 
operators. Such objects can be stored as elements of other ob¬ 
jects (both shared and private) without restriction. The allocation 
mode also has certain other effects that are explained below. 

The modifications made to the shared VM, including creation of 
new shared objects while in shared VM allocation mode, are not 
affected by subsequent execution of restore. That is, a restore 
does not undo the modifications to the shared VM, even if the 
matching save preceded the modificatons. It does, however, 
undo changes made to the private VM. Objects in shared VM are 
reclaimed only by the garbage collector; this occurs when those 
objects are no longer accessible from any context. 

Certain standard dictionaries are located in shared VM and 
others in private VM. Storing a shared object into a shared dic¬ 
tionary is the normal way of making that object visible to other 
contexts. The standard shared dictionaries are: 


systemdict the standard system dictionary, which is always read-only. 

Shareddict a new standard shared dictionary, which is writable by any context. This 
dictionary is stored as shareddict in systemdict. It is permanently on the 
dictionary stack, below userdict and above systemdict. 

SharedFontDirectory a dictionary consisting of fonts installed by executing definefont while in 
shared VM allocation mode. This dictionary is stored as SharedFontDirectory 
in systemdict. The findfont procedure looks first in the private FontDirectory, 
then in SharedFontDirectory. This is also the case for the new seiectfont 
operator (see Section 10). 


The standard private dictionaries 6 are: 


userdict the standard user dictionary. This dictionary is stored as userdict in 
systemdict; however, as viewed by each context, the value of userdict is the 
one located in that context’s private VM. 

errordict the standard error dictionary (stored as errordict in systemdict the same way 
as userdict). 

6 Although logically there is a separate instance of each of these dictionaries in 
each context’s private VM, they are implemented in such a way that a separate 
instance is created only if the dictionary is modified. This optimization is 
invisible to a PostScript language program. 
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statusdict the standard dictionary for product-specific operators, procedures, and 
parameters (stored as statusdict in systemdict the same way as userdict ). 7 

FontDirectory a dictionary consisting of fonts installed by executing definefont while in 
private VM allocation mode. Fonts so defined are private to the context that 
defined them. The findfont procedure looks first in FontDirectory, then in 
SharedFontDirectory. This dictionary is stored as FontDirectory in 
systemdict the same way as userdict. However, when shared VM allocation 
mode is in effect, the name FontDirectory is temporarily rebound to the value 
of SharedFontDirectory so that only shared fonts are visible; this ensures 
correct behavior of fonts that are defined in terms of other fonts. 

$error a dictionary accessed by the built-in error handler procedures (stored as $error 
in userdict). 


This organization is designed to permit font definitions to be ex¬ 
ecuted in either private or shared VM allocation mode. In the 
latter case, the font dictionary is created in shared VM and the 
definefont enters it into SharedFontDirectory, where it is 
available to all contexts. 

Although the principal intended use of shared VM is to hold font 
definitions, it is not limited to such use. Any definitions that are 
needed by several contexts may be placed in shared VM, saving 
both space and time. Additionally, shared VM can be used for 
active communication among contexts. However, several 
guidelines on use of shared VM must be observed in order to 
avoid unexpected behavior: 

• If a shared program defines a dictionary (or other data 
structure) to hold temporary data during execution of the 
program, it should create the dictionary in private VM upon 
first use of the program in a given execution context. Using 
a shared dictionary for this purpose could result in inter¬ 
ference between multiple contexts executing the same 
program. 

• For the reason just given, the prologues for most existing 
PostScript language applications may not work correctly if 
loaded into shared VM. Such prologues need to be restruc¬ 
tured to segregate the constant information, such as proce¬ 
dure definitions, from the variable information. 


7 statusdict is private instead of shared for compatibility with PostScript 
printers, in which certain device specific parameters are set by storing into 
statusdict. 
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• Programs that deliberately modify shared VM in order to 
accomplish intercontext communication may wish to take 
advantage of the mutual exclusion and synchronization 
primitives described in Section 5. 


5 MULTIPLE EXECUTION CONTEXTS 

The Display PostScript system is able to support the execution of 
multiple PostScript language programs concurrently. This capa¬ 
bility is required when multiple application programs share a 
single display system and window system. Additionally, it is 
sometimes advantageous for a single application to be structured 
as multiple concurrent processes. In this section, we describe the 
language extensions for managing the interactions between mul¬ 
tiple execution contexts. 

Applications normally access the Display PostScript system 
through the Client Library, which provides access to the 
PostScript imaging capabilities via procedures that can be called 
from an implementation language such as C or Pascal. The 
Client Library includes procedures for creating, communicating 
with, and destroying PostScript execution contexts. Strictly 
speaking, the Client Library facilities are not part of the 
PostScript language definition; they are described in the Client 
Library Reference Manual. 

Terminology and execution model 

A PostScript execution context (hereafter called simply a 
‘context’) consists of all the state that is visible to a running 
PostScript language program. This state includes: 

• an independent thread of control. Multiple threads can be in 
progress concurrently. 

• a set of stacks: operand stack, dictionary stack, execution 
stack, and graphics state stack. Starting from these stacks, 
one can access all state visible to a PostScript language 
program, such as dictionaries, paths, devices, etc. 

• a private VM or space, discussed below. 

• a shared VM, which is uniformly visible to all contexts (see 
Section 4). 
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• standard input and output files. In the Display PostScript 
system, these provide a means for communicating with an 
application program. 

• miscellaneous state variables, such as the current view clip 
(see Section 13), garbage collector control parameter 
(Section 4), object output format parameter (Section 3), and 
array packing mode (Appendix B). Unless otherwise docu¬ 
mented, any parameter that is not part of VM is private to 
each context. When a new context is created, all such 
parameters are initialized to their default state. 

A space is what we have called a private VM in Section 4. It 
includes userdict and all new composite objects created during 
normal execution of a context (except when the context invokes 
setshared and alters shared VM). 

In the usual case of multiple independent contexts serving mul¬ 
tiple independent applications, each context has its own space. 
Thus, the behavior of the contexts is decoupled to the maximum 
extent possible. Contexts can interact only by deliberately alter¬ 
ing shared VM; this is normally done only for the purpose of 
installing shared definitions such as fonts. At all other times, one 
can think of each context as a self-contained ‘virtual printer’. 

However, it is also possible for two or more contexts to use the 
same space. This implies a much closer degree of coupling 
among the contexts, since they must cooperate closely to main¬ 
tain their common space in a consistent state. This arrangement 
makes sense when multiple contexts are serving a single appli¬ 
cation program. For example, an application may manage mul¬ 
tiple instances of itself, as in a text editor with multiple windows. 
Or an application may itself be organized as several concurrent 
activities, such as tracking user interactions in the foreground 
while updating the displayed image in the background. 

An application program can call Client Library procedures, not 
described here, to create multiple contexts that use the same 
space. Additionally, an executing PostScript language program 
can create a new context sharing the current context’s space by 
executing the fork operator. It can also await completion of a 
previously forked context by executing the join operator. 

When multiple contexts share a single space, they require a 
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means to synchronize their activities. To facilitate this, the lan¬ 
guage has been extended to include two new types of objects and 
several new operators for manipulating them. 

A lock is a mutual exclusion semaphore that can be used by 
cooperating contexts to guard against concurrent access to data 
that they are sharing. A context acquires a lock before accessing 
the data and releases it afterward. During that time, other con¬ 
texts are prevented from acquiring the lock, thus preventing them 
from accessing the data when it is in a possibly inconsistent 
state. The association between a lock object and the data 
protected by the lock is entirely a matter of programming con¬ 
vention. 

A condition is a binary semaphore that can be used by 
cooperating contexts to synchronize their activity. One or more 
contexts can wait on a condition, i.e., suspend execution for an 
arbitrary length of time until notified by another context that the 
condition has been satisfied. Once again, the association between 
the condition object and the actual event or state that it 
represents is a matter of programming convention. 

Although the synchronization primitives are primarily intended 
for use by multiple contexts that share a single space, they can 
also be used by any contexts to synchronize access to data in 
shared VM. Of course, this requires prearrangement among all 
contexts involved; the lock and condition objects used for this 
purpose must themselves be in shared VM. 

Programming considerations 

In any environment that supports concurrent execution of inde¬ 
pendent threads of control, there is always the possibility of 
deadlock. The most familiar form of deadlock arises among two 
or more contexts when each waits for a notification from the 
other or each attempts to acquire a lock already held by the 
other. Another deadlock situation arises when all available com¬ 
munication buffers become filled with data for a context that is 
waiting for notification from some other context, but the other 
context cannot proceed because it has no way to communicate. 
Such deadlocks can be avoided only through careful system and 
application design. 
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Scheduling of contexts in unpredictable. In some environments, 
the PostScript interpreter may switch control among contexts at 
arbitrary times (i.e., preemptively); therefore, program execution 
in different contexts may be interleaved arbitrarily. Preemption 
may occur even within a single operator, such as one that causes 
a PostScript language procedure to be executed or that reads or 
writes a file. Therefore, to ensure predictable behavior, contexts 
should use the synchronization primitives to control access to 
shared data. 

Locks and conditions are ordinarily used together in a fairly styl¬ 
ized way; the language primitives are organized with this way of 
using them in mind. The monitor operator acquires a lock 
(waiting if necessary), executes an arbitrary PostScript language 
procedure, then releases the lock. The wait operator is executed 
within a procedure invoked by monitor; it releases the lock, 
waits for the condition to be satisfied, and reacquires the lock. 
The notify operator indicates that a condition has been satisfied 
and resumes any contexts waiting on that condition. 

The recommended style of use of wait and notify is based on the 
notion that a context first waits for a shared data structure to 
reach some desired state, then performs some computation based 
on that state, and finally alerts other contexts of any changes it 
has made to the data. A lock and a condition are used to imple¬ 
ment this protocol. The lock protects against concurrent access to 
the data; the condition is used to notify other contexts that some 
potentially interesting change has taken place. 8 

This protocol is illustrated by the following two program frag¬ 
ments; note that they are likely to be executed by different con¬ 
texts. 


8 Locks and conditions are treated separately because one may want to have 
several conditions that represent distinct states of the same shared data. 
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lockl 

{ 

{ 

... boolean expression testing monitored data ... 

{exit} {lockl condl wait} ifelse 
} loop 

... computation involving monitored data ... 

} monitor 

lockl 

{ 

... computation that changes monitored data ... 
condl notify 
} monitor 

The first program executes monitor to acquire the lock lockl ; it 
must do so to safely access the shared data associated with it. 
The program then checks whether the boolean expression has 
become true; it waits on the condition condl (repeatedly if 
necessary) until the expression evaluates to true. Now, while still 
holding the lock, it performs some computation based on this 
state of the shared data; note that it might alter the data in such a 
way that the boolean expression would evaluate false. Finally, it 
releases lockl by leaving the procedure invoked by monitor. 

The second program acquires lockl and then performs some 
computation that alters the data in a way that might favorably 
affect the outcome of the boolean expression. It then notifies 
condl and releases lockl. Any other context that is suspended at 
the wait in the first program now resumes and gets a chance to 
re-evaluate the boolean expression. 

Note that it is unsafe to assume that the state tested by the 
boolean expression is true immediately after resumption from a 
wait. Even if it was true at the moment of the notify, it might 
have become false due to intervening execution by some other 
context. Notifying condl does not necessarily certify that the 
value of the boolean expression is true, only that it might be true. 
Programs that conform to this protocol are immune from dead¬ 
locks due to Tost notifies’ or malfunctions due to ‘extra notifies’. 


5 MULTIPLE EXECUTION CONTEXTS 


33 



Restrictions 


Each context has its own private pair of standard input and out¬ 
put files. That is, different contexts obtain different file objects 
as a result of executing currentfile or applying the file operator 
to the names ‘%stdin’ and ‘%stdout\ A context should not at¬ 
tempt to make its standard input and output files available for 
use by other contexts; doing so will cause unpredictable be¬ 
havior. 

The standard input file carries data addressed to this context by 
the application; the standard output file carries data identified as 
coming from the current context to the application. Obviously, a 
program that executes fork must transmit the identity of the new 
context to the application in order for the application to address 
data to that context. (However, doing so is not always required, 
since some forked contexts have no need to communicate over 
their standard input and output files.) 

If multiple contexts share the same space, the semantics of save 
and restore become somewhat problematical. The operation per¬ 
formed by restore is logically to restore the entire space (i.e., the 
private VM) to its state as of the matching save. If one context 
does this, another context sharing the same space might observe 
the effect of the restore at some totally unpredictable time 
during its own execution; that is, its recent computations would 
be undone unexpectedly. This behavior is clearly not useful. 

Therefore, if any context executes a save, all other contexts shar¬ 
ing the same space are suspended until the original context ex¬ 
ecutes the matching restore. This ensures that the restore does 
not disrupt the activities of those other contexts. This restriction 
applies only to contexts sharing the same space; contexts associ¬ 
ated with other spaces proceed unhindered. 9 

Additionally, there are some restrictions on the synchronization 
operators that a context may execute while it has an unmatched 
save pending. For example, attempting to acquire a lock that is 
already held by another context sharing the same space is not 
allowed since it would surely lead to deadlock. 

9 Note that save and restore do not affect shared VM; therefore, contexts with 
separate spaces cannot interfere with each other by executing save and restore. 
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If a context terminates when it has an unmatched save pending, 
an automatic restore is executed, thereby allowing other con¬ 
texts to proceed. 

As a practical matter, save and restore are not of much use when 
a space is shared among multiple contexts. Programs that are 
organized in this way should avoid using save and restore. On 
the other hand, programs that are organized as one space per 
context can use save and restore without restriction. This is 
especially important to maintain compatibility with existing 
printing applications, font products, etc. 

Operators 

For the context operators, a context is an integer that identifies a 
PostScript execution context. Each context has a unique iden¬ 
tifier, whether it is created by calling a Client Library procedure 
or by executing the PostScript fork operator. This integer iden¬ 
tifies the context during communication between the application 
and the Display PostScript system as well as during execution of 
the join and detach operators. Identifiers for contexts that have 
terminated become invalid and are not reused during the lifetime 
of any currently active session. The currentcontext operator 
returns the identifier for the context that is executing. 

A context can suspend its own execution by any of a variety of 
means: execute the wait, monitor, or yield operators or return 
from its top-level procedure to await a join. The context retains 
all the state it had at the moment of suspension and can or¬ 
dinarily be resumed from the point of suspension. 

A context can terminate by executing the quit operator or as a 
result of an explicit termination request from the Client Library. 
Termination also occurs if an error occurs that is not caught by 
an explicit use of stopped. When a context terminates, its stacks 
are destroyed, its standard input and output files are closed, and 
its context identifier becomes invalid. 

There is no hierarchical relationship among contexts. Termina¬ 
tion of a context has no effect on other contexts that it may have 
created. An integer that identifies a context has the same mean¬ 
ing in every context; it may be referenced in a context different 
from the one that created it. 
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The objects lock and condition are distinct types of PostScript 
object. They are composite objects in the sense that their values 
occupy space in VM separate from the objects themselves; when 
a lock or condition object is stored in multiple places, all the 
instances share the same value. However, the values of locks and 
conditions are not directly accessible; they are accessed im¬ 
plicitly by the synchronization operators described above. 

An invalidcontext error occurs if an invalid context identifier is 
presented to any of the context operators or if any of the pro¬ 
gramming restrictions are violated. 


6 USER OBJECTS 

Some applications require a convenient and efficient way to refer 
to PostScript language objects previously constructed in VM. 
Some types of objects, such as dictionaries and gstates, are not 
visible as data outside the PostScript interpreter; that is, they 
cannot be represented or referenced directly in any encoding of 
the language, even binary object sequences. Instead, the appli¬ 
cation must refer to such objects by means of surrogate objects, 
such as names or integers, whose values can be encoded and 
communicated easily. 

The traditional way to accomplish this is to store such objects as 
elements of dictionaries or arrays and later to refer to them with 
their dictionary keys or array indices. In a PostScript language 
program written by a programmer, this approach is natural and 
straightforward. When the program is generated mechanically by 
another program, however, managing the space of surrogate ob¬ 
jects (names or integers) requires additional bookkeeping. This is 
true particularly when the set of objects being managed is 
dynamically varying and when the responsibility for creating and 
referencing them is distributed among multiple libraries or pack¬ 
ages. 

pswrap provides a way for an application program to refer to 
user objects conveniently. This facility is described in the 
pswrap Reference Manual. 

To support user objects, the Display PostScript system provides 
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three new operations: defineuserobject, undefineuserobject, 
and execuserobject, which manipulate an array named 
UserObjects. These operations introduce no fundamentally new 
capabilities; their behavior can be described entirely in the 
PostScript language and they can be implemented as procedures 
rather than as operators. 10 They have been made a standard part 
of the language so that pswrap can depend on their being avail¬ 
able. 

The following example illustrates the intended use of user ob¬ 
jects. 


/Times-Roman findfont 12 scalefont 
17 exch defineuserobject 

The first line of the example obtains a user object (in this case, a 
font dictionary). The second line associates the user object index 
17 with this dictionary. Subsequently, 

17 execuserobject setfont 

pushes the font dictionary on the operand stack, from which it is 
taken by setfont. execuserobject executes the user object associ¬ 
ated with index 17; however, since the object in this example is 
not executable, the result of the execution is to push the object 
onto the operand stack. 


7 GRAPHICS STATE OBJECTS 

The PostScript graphics state consists of a large collection of 
parameters that are accessed implicitly by the imaging operators. 
These parameters can be read and altered individually; the entire 
graphics state can be saved by pushing it on a stack (gsave) and 
restored by popping it from the stack (grestore). 

This organization serves the needs of printing applications very 
well, assuming that the documents to be printed are reasonably 
structured. However, in interactive applications to be served by 
the Display PostScript system, a program needs to switch its at- 

10 User objects are entirely different from user names, described in Section 2. 
User names are part of the binary encoding extensions of the PostScript lan¬ 
guage syntax. 
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tention among multiple, more-or-less independent imaging con¬ 
texts in an unpredictable order. Switching entire graphics states 
by altering their components individually is cumbersome and in¬ 
efficient. 

To address this need, we have introduced a new type of object, 
the gstate, that is capable of representing an entire graphics state. 
A gstate is a composite object that occupies VM and that con¬ 
forms to the normal save/restore discipline; it is created by the 
gstate operator. The type operator returns the name gstatetype 
when a gstate is its operand. 

The operators setgstate, currentgstate, and copy read and alter 
a gstate’s value as a whole by copying it to or from the current 
graphics state or another gstate object. There is no way to select 
individual elements of a gstate’s value directly; however, this 
can be accomplished by copying the gstate to the current 
graphics state temporarily and then accessing it using the regular 
graphics state operators. 

Note that a gstate object captures every element of a graphics 
state, including such things as the current path and current clip 
path. For example, if a non-empty current path exists at the time 
gstate or currentgstate is executed, that path will be reinstated 
by the corresponding setgstate. Unless this effect is specifically 
desired, it is best to snapshot a graphics state only when the cur¬ 
rent path is empty and the current clip path is in its default state. 


8 USER PATHS 

A user path is a PostScript language procedure consisting en¬ 
tirely of path construction operators and their coordinate 
operands expressed as literal numbers. In other words, it is a 
completely self-contained description of a path in user space. 
There exist several new operators that combine execution of a 
user path description with rendering the resulting path (i.e., using 
it for filling or stroking). 

The construction and use of a user path are best illustrated by an 
example: 
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{ 

ucache % this is optional 

100 200 400 500 setbbox % this is required 
150 200 moveto 

250 200 400 390 400 460 curveto 
400 480 350 500 250 500 curveto 
100 400 lineto 
closepath 
} 

ufill 

The tokens enclosed in ‘{’ and *}’ constitute a user path defini¬ 
tion. The setbbox operator, with its four numeric operands 
(integers or reals), must appear first, or immediately after the 
optional ucache; the setbbox and ucache operators are described 
below. The remainder of the user path consists of path construc¬ 
tion operators and their operands, in any sensible order. The path 
is assumed to start out empty, so the first operator after the 
setbbox must be an absolute positioning operator (moveto, arc, 
or arcn). 

ufill is one of the new combined path construction and rendering 
operators. Its effect is to interpret the user path as if it were an 
ordinary PostScript language procedure (in the context of 
systemdict), then to perform a fill. Moreover, it performs a 
newpath prior to interpreting the user path and it encloses the 
entire operation with a gsave and a grestore. Thus, the overall 
effect of the above example is to define a path and to paint its 
interior with the current color; it leaves no side effects in the 
graphics state (or anywhere else except in raster memory). 

The user path rendering operators can be fully described in terms 
of the existing PostScript language facilities; they introduce no 
fundamentally new capability. There are several motivations for 
having an integrated user path facility as a standard part of the 
language: 

• It closely matches the needs of many application programs. 
In particular, it fits very well with the Display PostScript 
Client Library organization. If the language did not provide 
a user path facility, most applications would have to invent 
one. 

• A user path consists of path construction operators and 
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numeric operands, not arbitrary computations. Thus, the 
user path is self-contained; its semantics are guaranteed not 
to depend on an unpredictable execution environment. Ad¬ 
ditionally, the information provided by setbbox assures that 
the coordinates of the path will be within predictable 
bounds. As a result, interpretation of a user path may be 
much more efficient than execution of an arbitrary 
PostScript language procedure. 11 

• Because a user path is represented as a procedure object 
and is self-contained, the PostScript interpreter can save the 
results of executing it in a cache. This may eliminate redun¬ 
dant interpretation of the same path definition, which is im¬ 
portant in some Display PostScript applications that update 
the display frequently. 

User path construction 

A user path is an array or packed array object consisting of the 
following sequences of elements: 

ucache 

// x // y ur x ur y setbbox 

xy moveto 

dxdy rmoveto 

xy lineto 

dxdy rlineto 

*1 Y\ *2 Y 2 *3 y 3 curveto 

dx 1 dy^ dx 2 dy 2 dx 3 dy 3 rcurveto 

xyrang 1 ang 2 arc 

xyrang 1 ang 2 arcn 

Yi * 2 Yz r arct 
closepath 

The permitted operators are all the standard PostScript operators 
that append to the current path, with the exception of arcto and 
char path, which are not allowed. Additionally, there are three 
new user path construction operators: ucache, setbbox, and arct, 
which are described below. The permitted operands are number 


n The user path rendering operators that are defined not to alter the current path 
may not create an explicit path at all. Indeed, if the bounding box lies com¬ 
pletely outside the current clipping path, execution of the path definition and 
the rendering operation may be bypassed altogether. This behavior is, however, 
completely invisible to the PostScript language program. 
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literals, i.e., integers and reals. The correct number of operands 
must be supplied to each operator. Any deviation from these 
rules will result in a typecheck error when the user path is inter¬ 
preted. 

The user path begins with an optional ucache, whose purpose is 
described below. Immediately following this must be a setbbox 
sequence, which establishes a bounding box (in user space) 
enclosing the entire path. All coordinates specified as operands 
to the subsequent path construction operators must fall within 
these bounds; if they don’t, a rangecheck error will occur when 
the user path is interpreted. 

The path construction operators in a user path may appear either 
as executable name objects, such as ‘moveto’, or as actual 
PostScript operator objects, such as the value of ‘moveto’ in 
systemdict. An application program constructing a user path 
specifies name objects; however, applying bind to the user path 
(or to a procedure containing it) ordinarily causes the names to 
be replaced by the operator objects themselves. 

The user path rendering operators interpret a user path as if 
systemdict were the current dictionary (see the definition of 
uappend); thus, the path construction operators contained in the 
user path are guaranteed to have their standard meanings. It is 
illegal for a user path to contain names other than the standard 
path construction operator names. Aliases are prohibited so as to 
ensure that the user path definition is self-contained and its 
meaning is entirely independent of its execution environment. 

Encoded user paths 

An encoded user path is a very compact representation of a user 
path. It is an array consisting of two PostScript string objects (or 
an array and a string). The strings effectively encode the 
operands and operators of an equivalent user path procedure, 
using a compact binary encoding. 

The encoded user path representation is accepted and understood 
by the user path rendering operators such as ufill. Those 
operators interpret the data structure and perform the encoded 
operations; it does not make sense to think of ‘executing’ the 
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encoded user path directly. 12 When we say that an encoded value 
represents an operation such as moveto, we mean the standard 
moveto operation; as with unencoded user paths, there is no op¬ 
portunity to redefine the meanings of operators represented in an 
encoded user path. 

The first element of an encoded user path is a data string or data 
array containing numeric operands; the second is an operator 
string containing encoded operators. This two-part organization 
is for the convenience of application programs that generate en¬ 
coded user paths; in particular, operands always fall on natural 
addressing boundaries. All the characters in both strings are in¬ 
terpreted as binary numbers, not as ASCII character codes. 

If the first element is a string, it is interpreted as an encoded 
number string, whose representation is described in Section 2. If 
it is an array, its elements are simply used in sequence; they must 
all be numbers. 


The operator string is interpreted as a sequence of encoded path 
construction operators, one operation code (opcode) per charac¬ 
ter. (Unlike the data string, the operator string is not interpreted 
as an encoded number string.) The allowed opcode values are as 
follows: 

0 setbbox 

1 moveto 

2 rmoveto 

3 lineto 

4 rlineto 

5 curveto 

6 rcurveto 

7 arc 

8 arcn 

9 arct 

10 closepath 

11 ucache 

n > 32 repetition count: repeat next opcode n - 32 times 


12 In principle, one could write a PostScript language program to perform this 
interpretation: this is analogous to writing an emulator for another language. 
Note that the operator encoding is specialized to user path definitions; it has 
nothing to do with the alternative external encodings of the PostScript lan¬ 
guage, which are described in Section 2. 
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Associated with each opcode in the operator string are zero or 
more operands in the data string or data array. The order of the 
operands is the same as in an ordinary user path. For example, 
execution of a lineto (opcode 3) consumes an jc operand and a y 
operand from the data sequence. 

If the encoded user path does not conform to the rules described 
above, a typecheck error will occur when the path is interpreted. 
Possible errors include invalid opcodes in the operator string or 
premature end of the data sequence. 

User path cache 

Interactive applications using the Display PostScript system typi¬ 
cally define certain paths that must be redisplayed frequently or 
that are repeated many times. To optimize interpretation of such 
paths, the Display PostScript system provides a facility called the 
user path cache. This cache, analogous to the font cache, retains 
the results of interpreting user path definitions. When the 
PostScript interpreter encounters a user path that is already in the 
cache, it substitutes the cached results instead of reinterpreting 
the path definition. 

There is a non-trivial cost associated with placing a user path in 
the cache: extra computation is required and existing paths may 
be displaced from the cache. Since most user paths are used once 
and immediately thrown away, it does not make sense to place 
every user path in the cache. Instead, the application program 
must explicitly identify the user paths that are to be cached. It 
does so by including the ucache operator as the first element of 
the user path definition (before the setbbox sequence), as shown 
in the following example: 

/Circlel {ucache -1-111 setbbox 0 0 1 0 360 arc} 
cvlit def 

Circlel ufill 

The ucache operator notifies the PostScript interpreter that the 
enclosing user path should be placed in the cache if it is not 
already there or obtained from the cache if it is. This cache 
management is not performed directly by ucache; instead, it is 
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performed by the user path rendering operator that interprets the 
user path (ufill in this example). This is because the results 
retained in the cache differ according to what rendering opera¬ 
tion is performed. 13 The ufill produces the same effects on the 
current page whether or not the cache is accessed. 

Caching is based on the value of a user path object. That is, two 
user paths are considered the same for caching purposes if all 
elements of one are equal to the corresponding elements of the 
other, even if the objects themselves are not equal. Thus, a user 
path placed in the cache need not be explicitly retained in VM; 
an equivalent user path appearing literally later in the program 
can take advantage of the cached information. (Of course, if it is 
known that a given user path will be used many times, defining it 
explicitly in VM avoids creating it multiple times.) 

User path caching, like font caching, is effective across trans¬ 
lations of the user coordinate system, but not across other trans¬ 
formations such as scaling or rotation. In other words, multiple 
instances of a given user path rendered at different places on the 
page take advantage of the user path cache when the CTM is 
altered only by translate. If the CTM is altered by scale or 
rotate, the instances will be treated as if they were described by 
different user paths. 

Two other features of the above example should be noted. First, 
the user path object is explicitly saved for later use (as the value 
of ‘Circlel’ in this example). This is done in anticipation of 
rendering the same path multiple times (in this case, a one-unit 
circle). Second, the cvlit operator is applied to the user path ob¬ 
ject in order to remove its executable attribute. This is to ensure 
that the subsequent reference to ‘Circlel’ simply pushes the ob¬ 
ject on the operand stack rather than inappropriately executing it 
as a procedure. (It is unnecessary to do this if the user path isn’t 
saved for later use but is simply consumed immediately by a user 
path rendering operator.) 


13 For this reason, it does not make sense to invoke ucache outside a user path; 
doing so has no effect. 
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Operators 

There are four categories of user path operators: 

• New path construction operators, intended for inclusion in 
user path definitions (but not limited to such use), i.e., 
setbbox, arct. 

• User path rendering operators, combining interpretation of 
a user path with a rendering operation (fill or stroke), i.e., 

ufill, ueofill, ustroke. 

• User path cache operators, providing the ability to control 
and query the operation of the user path cache, i.e., ucache, 
ucachestatus, setucacheparams. 

• miscellaneous operators that involve user paths, i.e., 

uappend, upath, ustrokepath, inufill, inueofill, 
inustroke 

A userpath is one of the following: 

• an ordinary user path: an array (which need not be 
executable) whose length is at least 5; 

• an encoded user path: an array of two elements. The first 
element must be either an array whose elements are all 
numbers or a string that can be interpreted as an encoded 
number string (see Section 2). The second must be a string 
that encodes a sequence of operators, as described above. 

In either case, the value of the object must conform to the rules 
for constructing user paths, as detailed in preceding sections; that 
is, the operands and operators must appear in the correct se¬ 
quence. If the user path is malformed, a typecheck error will 
occur. 

Several of the operators take an optional matrix as their topmost 
operand. This is a six-element array of numbers that describe a 
transformation matrix, as described in Section 4.4 of the 
PostScript Language Reference Manual. A matrix is distin¬ 
guished from a user path (which is also an array) by the number 
and types of its elements. 

In several of the descriptions of user path operators, the seman¬ 
tics of an operator are described as being ‘equivalent’ to a 
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PostScript language program making use of lower-level 
operators. This does not necessarily mean that the implemen¬ 
tation executes those lower-level operators explicitly; in par¬ 
ticular, redefining those operator names will not affect the be¬ 
havior of the high-level operator. The effect is as if the 
‘equivalent’ PostScript language program has had bind applied 
to it with systemdict as the current dictionary. Furthermore, the 
‘equivalent’ program cannot take advantage of the user path 
cache. 

Most of the user path rendering operators have no effect on the 
graphics state. The absence of side effects is a significant reason 
for the efficiency of the operations; in particular, there is no need 
to build up an explicit current path only to discard it after one 
use. Although the behavior of the operators can be described as 
if the path were built up, rendered, and discarded in the usual 
way, the actual implementation of the operators is optimized to 
avoid unnecessary work. Note that there is no user path clip 
operation. Since the whole purpose of the clip operation is to 
alter the current clipping path, there is no way to avoid actually 
building the path. The best way to clip with a user path is: 

newpath userpath uappend clip newpath 

This operation can still take advantage of information in the user 
path cache under favorable conditions. 

The uappend operator and the rendering operators defined in 
terms of uappend, such as ufill, perform a temporary adjustment 
to the current transformation matrix as part of their execution. 
This adjustment consists of rounding the t x and t y components of 
the CTM to the nearest integer values. The purpose of this is to 
ensure that scan conversion of the user path produces uniform 
results when it is placed at different positions on the page 
through translation; it is especially important if the user path is 
cached. This adjustment is not ordinarily visible to a PostScript 
language program; it is not mentioned in the descriptions of the 
individual operators. 
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9 RECTANGLES 


Rectangles are used very frequently, especially in display appli¬ 
cations. Thus, it is useful to have a few primitives to render rec¬ 
tangles directly. This is a convenience to application programs; 
additionally, the foreknowledge that the figure will be a rec¬ 
tangle results in significantly optimized execution. 

A rectangle is defined in the user coordinate system. The result 
produced is identical to that of a rectangle defined as an ordinary 
path. The rectangle operators are rectfill, rectstroke, rectclip, 
and rectviewclip. 

The rectangle operators accept three different forms of operands. 
The first form is simply four numbers: x, y, width, and height, 
which describe a single rectangle. The rectangle’s sides are 
parallel to the user space axes; it has comers located at (x, y), 
(x + width, y), (x + width, y + height), and (x, y + height). Note 
that width and height can be negative. 

The other two forms are an indefinitely long sequence of num¬ 
bers, represented either as an array or as an encoded number 
string; this representation is described in Section 2. The sequence 
must contain a multiple of four numbers; each group of four con¬ 
secutive numbers is interpreted as the x, y, width, and height 
values defining a single rectangle. The effect produced is equiv¬ 
alent to specifying all the rectangles as separate subpaths of a 
single combined path, which is then rendered by a single fill, 
stroke, or clip operator. 

All rectangles are drawn in a counterclockwise direction in user 
space, regardless of the signs of the width and height operands. 
This ensures that when multiple rectangles overlap, all of their 
interiors are treated as ‘inside’ the path according to the non-zero 
winding number rule. In the operator descriptions in Section 16, 
the programs stated to be ‘equivalent’ to the operators are valid 
only for positive width and height values; more complex 
programs are required to deal with negative values. 
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10 FONT-RELATED EXTENSIONS 

Explicit character positioning 

The standard operators for setting text (show and its variants) are 
designed according to the assumption that characters are or¬ 
dinarily shown with their standard metrics. Means are provided 
to vary the metrics in certain limited ways: the ashow operator 
systematically adjusts the widths of all characters of a string 
during one show operation; the optional Metrics entry of a font 
dictionary adjusts the widths of all instances of particular charac¬ 
ters of a font. 

Certain applications that set text require very precise control over 
the positioning of each character. Although it is possible to posi¬ 
tion characters individually by executing a moveto and a single 
character show for each one, this approach is too cumbersome 
and expensive for setting more than small amounts of text. When 
an application has gone to the trouble of computing the positions 
of individual characters, it should have a reasonable way to ex¬ 
press those positions directly. 

Three new variants of the show operator have been defined to 
streamline the setting of individually positioned characters: 
xyshow, xshow, and yshow. Each operator is given a string of 
text to be shown, just the same as show. Additionally, it expects 
a second operand, which is either an array composed of numbers 
or a string that can be interpreted as an encoded number string as 
described in Section 2. The numbers are used in sequence to con¬ 
trol the widths of the characters being shown, i.e., the spacing 
between each character and the next. They completely override 
the standard widths of the characters. 

Each number (or, for xyshow, each pair of consecutive numbers) 
is associated with the corresponding character of the text string 
being shown. For a basic PostScript font, this is the entire story. 
For a composite font, which may have a complex mapping from 
characters in the show string to glyphs rendered on the page, 
successive elements of the number array or the encoded number 
string are associated with successively rendered glyphs. 
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Font selection 


Applications that frequently switch fonts require a streamlined 
means for doing so. The canonical sequence findfont, scalefont 
(or makefont), and setfont appears so frequently that most ap¬ 
plications define a procedure to perform it. The cost of this pro¬ 
cedure, as well as findfont (which is itself a procedure) and 
scalefont (which performs rather extensive computations), can 
have a serious impact on efficiency. 

To better support the needs of applications, we have introduced a 
new operator, selectfont, that combines the actions of the above 
three operators. This operator takes advantage of information in 
the font cache in order to avoid calling findfont or performing 
the scalefont or makefont computations unnecessarily. Thus, in 
the common case of selecting a font and size combination that 
has been used recently, selectfont works with great efficiency. 

Outline and bitmap font coordination 

In display systems, the resolution of the device is typically quite 
low; resolutions in the range of 60 to 100 pixels per inch are 
common. When characters are produced algorithmically from 
outlines in typical sizes (10 to 12 points), the results are often not 
as legible as they need to be for most comfortable reading. The 
usual way to deal with this problem is to use screen fonts con¬ 
sisting of bitmap characters that have been tuned manually. The 
hand tuning increases legibility, possibly at the expense of 
fidelity to the original character shapes. 

The Display PostScript system includes the ability to take advan¬ 
tage of hand-tuned bitmap fonts when they are available. This 
facility is fully integrated with the standard PostScript font 
machinery; its operation is almost totally invisible to a PostScript 
language program. 

When a program sets text by executing an operator such as 
show, the PostScript interpreter first consults the font cache in 
the usual way. If the character is not there, it next consults the 
current device, requesting it to provide a bitmap form of the 
character at the required size. If the device can provide such a 
bitmap, it does so; the PostScript interpreter places the bitmap in 


10 FONT-RELATED EXTENSIONS 


49 



the font cache for subsequent use. If there is no such character, 
the interpreter executes the character description in the usual 
way, placing the scan converted result in the font cache. 

The mechanism by which bitmap characters are provided by a 
device is not part of the language and is entirely hidden from a 
PostScript language program. In an integration of the Display 
PostScript system with a window system, the implementation of 
the device is the responsibility of the window system. Thus, the 
conventions for locating and representing bitmap characters are 
environment dependent. (Re-encoding a font preserves the as¬ 
sociation with bitmap characters; most other modifications to a 
font dictionary destroy the association.) 

Bitmap fonts are typically provided in one orientation and a 
range of sizes from 10 to 24 points. (Beyond 24 points, charac¬ 
ters scan converted from outlines are perfectly acceptable.) The 
PostScript interpreter can usually choose a bitmap character 
whose size is sufficiently close to the one requested and render it 
directly. 

Associated with each hand-tuned bitmap is a width, i.e., dis¬ 
placement from the origin of the character to the origin of the 
next character. This width is also hand tuned for maximum 
legibility; it is an integer interpreted in device space (i.e., in 
character space, since pixels are pixels). It is usually different 
from the width produced when the same character is scan con¬ 
verted from the font definition, since that width (the scaleable 
width ) is defined by real numbers that are scaled according to the 
requested font size. 14 

To achieve true fidelity between displays and printers when 
rendering characters, an application must use the scaleable 
widths to position characters on the display. Unfortunately, this 
leads to uneven letter spacing due to the need to round character 
positions to device pixel boundaries; at display resolution, this 
unevenness is objectionable. On the other hand, using the integer 
bitmap widths to produce evenly spaced text on the display leads 
to incorrect results on the printer. The only reasonable solution is 


14 Hand tuned bitmaps are carefully designed so that the bitmap widths and 
scaleable widths are as similar as possible when averaged over large amounts 
of text. 
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to use bitmap widths on the display and scaleable widths on the 
printer and to compensate for the positioning discrepancies in 
some other way. 

Many word processing and page layout programs already use the 
following technique when rendering text on the display: 

• Set the characters according to their integer bitmap widths, 
but keep track of the accumulated difference between the 
bitmap widths and the true scaleable widths. 

• Adjust the spaces between words to compensate for the ac¬ 
cumulated error. The most accurate way to do this is first to 
compute the error for an entire line and then to distribute 
the accumulated error among all the spaces in that line. 

This technique maintains fidelity between display and printer on 
a line-by-line basis. 

An application can control whether bitmap widths or scaleable 
widths are to be used on a per-font basis by adding a new entry, 
BitmapWidths, to the top-level font dictionary. If this entry is 
present, it must have a boolean value: true indicates that bitmap 
widths are to be used when the device provides bitmaps for this 
font; false indicates that scaleable widths are to be used. If the 
entry is not present or if the device does not provide bitmaps for 
this font, the normal scaleable widths are used always. 

A device implementation ordinarily uses hand-tuned bitmaps 
only when the following conditions are met: 

• The coordinate system axes are perpendicular (that is, the 
transformations are not skewed). 

• The scale is uniform (reflections about axes are allowed). 

• The angle of rotation is an even multiple of 90 degrees (0, 
90,180, or 270). 

The appearance of the hand-tuned bitmaps is usually preferable 
to that of scan-converted outlines for a given character at a given 
point size. 

Hand-tuned bitmaps are provided in a range of discrete sizes. 
When a requested size falls between two discrete sizes, the 
closest discrete size can be used and the widths are scaled ac- 
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cordingly. In all other cases, the default is to use scan-converted 
outlines. In certain cases a developer may deem it preferable to 
produce transformations of the bitmaps rather than scan¬ 
converting the transformed outlines. 

Three keys can be added to the top-level font dictionary to con¬ 
trol these transformations: 

ExactSize Refers to cases where there is an exact match 
between the requested size and a hand-tuned bit¬ 
map when the coordinate system axes are per¬ 
pendicular, the scale is uniform, and the angle of 
rotation is an even multiple of 90 degrees. 

InBetweenSize Refers to cases where the requested size falls be¬ 
tween discrete hand-tuned bitmap sizes under 
the same conditions as ExactSize. 

TransformedChar 

Refers to cases where the transformation is other 
than those mentioned under ExactSize con¬ 
ditions. 

Each of these keys (ExactSize, InBetweenSize, and 
TransformedChar) can take one of the following values to con¬ 
trol the use of hand-tuned bitmaps: 

0 Use outline 

1 Use closest hand-tuned bitmap size 

2 Use transformed hand-tuned bitmap 

Not all implementations are able to transform hand-tuned bit¬ 
maps. The default values for the additional keys are specified 
below: 
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Key 


Default Value 


BitmapWidths 

ExactSize 

InBetweenSize 

TransformedChar 


false 

1 (closest hand-tuned bitmap) 
1 (closest hand-tuned bitmap) 
0 (outline) 


11 HALFTONE DEFINITION 

Halftoning is the process by which continuous gray tones are 
approximated by a pattern of pixels that can achieve only a 
limited number of discrete gray tones. The most familiar case of 
this is rendering of gray tones with black and white pixels. In the 
original PostScript language, program control of the halftoning 
process is provided by means of the setscreen operator, 
described in Section 4.8 of the PostScript Language Reference 
Manual. 

As PostScript interpreters are integrated with a wider assortment 
of printing and display technologies, the language must be ex¬ 
tended to provide more control over details of the halftoning 
process. For example, in color printing, one must specify inde¬ 
pendent halftone screens for each of three or four color separa¬ 
tions. In imaging on low-resolution displays, one must have finer 
control over the halftoning process in order to achieve the best 
approximations of gray levels or colors and to minimize artifacts. 

In recognition of the need to provide new halftoning processes 
with new printing and display technologies, we have introduced 
an extensible mechanism for defining halftones. This 
mechanism, called the halftone dictionary, provides means to 
define any of several types of halftones. The setscreen style of 
halftone is one of these types; new types (or new variations on 
those types) do not require fundamental language changes. 

Remember that everything relating to halftones is, by definition, 
device dependent. In general, when an application defines its 
own halftones, it sacrifices portability. Associated with every 
device is a default halftone definition that is appropriate for most 
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applications. Only relatively sophisticated applications need to 
define their own halftones to achieve special effects. 

Halftone dictionaries 

A halftone dictionary is an ordinary PostScript dictionary object, 
certain of whose key-value pairs have special meanings. Some of 
the contents of a halftone dictionary are optional and user- 
definable, while other key-value pairs must be present and have 
the correct semantics in order for the halftone machinery to 
operate properly. In this respect (as in several others), a halftone 
dictionary is analogous to a font dictionary. 

The graphics state includes a current halftone dictionary, which 
specifies the halftoning process to be used by the painting 
operators. The operator currenthalftone returns the current 
halftone dictionary; sethalftone establishes a different halftone 
dictionary as the current one. 

A halftone dictionary is a self-contained description of a halfton¬ 
ing process. Painting operations, such as fill, stroke, and show, 
consult the current halftone dictionary when they require infor¬ 
mation about the halftoning process. Some of the entries in the 
dictionary are procedures that are called to compute the required 
information. 

The PostScript interpreter consults the halftone dictionary at un¬ 
predictable times. Furthermore, it can cache the results internally 
for later use; such caching may persist through switches of 
halftone dictionaries caused by sethalftone, gsave, and grestore. 
For these reasons, once a halftone dictionary has been passed to 
sethalftone, its contents should be considered read-only. 
Procedures in the halftone dictionary must compute results that 
depend only on information in the halftone dictionary, not on 
outside information, and they must not have side-effects. 15 

Every halftone dictionary must have a HalftoneType entry 
whose value is an integer. This specifies the major type of 

15 This rules out certain ‘tricks’, such as the pattern fill example in the 
PostScript Language Tutorial and Cookbook , that depend on the spot function 
being executed at predictable times. Such tricks continue to work for halftones 
defined by setscreen, but not for halftones defined by halftone dictionaries. 
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halftoning process; the remaining entries in the dictionary are 
interpreted according to the type. The halftone types currently 
defined are: 

1 The halftone is defined by frequency, angle, and spot func¬ 
tion (corresponding to the existing setscreen facility). 

2 The halftone is defined by four separate frequency, angle, 
and spot functions: one for each of the three primary colors 
(red, green, and blue) plus gray. 

3 The halftone is defined directly by a threshold array at 
device resolution. 

4 The halftone is defined by four threshold arrays: one for 
each of the three primary colors plus gray. 

If the current halftone has been defined by sethalftone instead of 
by setscreen, a subsequent currentscreen will return a fre¬ 
quency of 60, an angle of 0, and the halftone dictionary as the 
spot function. If setscreen receives a dictionary as a spot func¬ 
tion, it will ignore the frequency and angle parameters and per¬ 
form the equivalent of sethalftone on the dictionary. This be¬ 
havior is for compatibility with existing applications that attempt 
to alter the screen frequency or angle without providing a new 
spot function. Such applications cannot produce the intended ef¬ 
fect but still run to completion. 

Spot functions 

A type 1 halftone dictionary defines a halftone in terms of its 
frequency, angle, and spot function. These parameters have the 
same meanings as the operands given to setscreen, but they are 
provided as entries in a halftone dictionary. The entries are as 
follows: 


Key Type Semantics 


HalftoneType integer 
Frequency number 

Angle number 


must be 1. 

screen frequency, measured in halftone cells per inch in device space. 

screen angle: number of degrees by which the screen is to be rotated with 
respect to the device coordinate system. 


11 HALFTONE DEFINITION 


55 





SpotFunction 


procedure 


procedure that defines the order in which device pixels within a screen cell are 
adjusted for different gray levels. 


A halftone defined in this way produces results identical to a 
halftone defined by setscreen. However, the dictionary form of 
this halftone definition can work more efficiently since the 
PostScript interpreter can retain information about it in a cache, 
which it is not permitted to do for a halftone specified by 
setscreen. See the previous section for a discussion of this mat¬ 
ter. 

A type 2 halftone dictionary defines a halftone as four screens in 
the same manner as setcolorscreen. Instead of a single 
Frequency entry, there are entries for RedFrequency, 
GreenFrequency, BlueFrequency, and GrayFrequency; 
likewise for Angle and SpotFunction. Color screens are not fur¬ 
ther discussed here; see PostScript Language Color Extensions 
for more information. 

Threshold arrays 

A type 3 halftone dictionary defines a halftone as an array of 
threshold values that directly control individual device pixels in 
a halftone cell. This provides a finer degree of control over 
halftone rendering; also, it permits halftone cells to be rectan¬ 
gular, whereas halftone cells defined by a spot function are al¬ 
ways square. Both of these capabilities are important for low- 
resolution display applications. 

A threshold array is much like a sampled image: it is a 
rectangular array of pixel values. However, it is defined entirely 
in device space and the sample values always occupy 8 bits each. 
The pixel values nominally represent gray levels in the usual 
way, where 0 is black and 255 is white. The threshold array is 
replicated to tile the entire device space; thus, each pixel of 
device space is mapped to a particular sample of the threshold 
array. 

On a bilevel device (each pixel is either black or white), the 
halftoning algorithm is as follows. For each device pixel that is 
to be painted with some gray level, the corresponding pixel of 
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the threshold array is consulted. If the desired gray level is less 
than the pixel value in the threshold array, the device pixel is 
painted black; otherwise it is painted white. For the purpose of 
this comparison, gray values in the range 0 to 1 (inclusive) cor¬ 
respond to pixel values 0 to 255 in the threshold array. 

This scheme easily generalizes to monochrome devices with 
multiple bits per pixel. For example, if there are 2 bits per pixel, 
then each pixel can directly represent one of four different gray 
levels: black, dark gray, light gray, and white, encoded as 0, 1, 2, 
and 3 respectively. For each device pixel that is to be painted 
with some in-between gray level, the corresponding pixel of the 
threshold array is consulted to determine whether to use the next 
lower or next higher representable gray level. In this situation, 
the samples in the threshold array do not represent absolute gray 
values but gradations between two adjacent representable gray 
levels. 

With this approach, it is reasonable to use the same threshold 
array for monochrome displays having different numbers of gray 
levels. This works because the threshold values are effectively 
scaled to span the distance between adjacent representable gray 
values, regardless of how many distinct gray values there are. 
(Indeed, the halftone rendering algorithm for a single bit per 
pixel device is simply a special case of the one for multiple bits 
per pixel.) 

A type 3 halftone dictionary must contain the following entries: 
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Key 

Type 

Semantics 

HalftoneType 

integer 

must be 3. 

Width 

integer 

width of threshold array, in pixels. 

Height 

integer 

height of threshold array, in pixels. 

Thresholds 

string 

threshold values. This string must be width x height characters long. The 
individual characters represent threshold values as described above. The order 
of pixels is the same as for a sampled image mapped directly onto device space, 
with the first sample at the lower left comer 16 and x coordinates changing faster 
than y coordinates. 


A halftone defined in this way can also be used with color 
(RGB) displays. The red, green, and blue values are simply 
treated independently as gray levels; the same threshold array 
applies to each color. 

However, some devices, particularly color printers, require 
separate halftones for each primary color (and sometimes also 
for gray). A type 4 halftone dictionary defines four separate 
threshold arrays. Instead of a single Width entry, there are 
entries for RedWidth, GreenWidth, BlueWidth, and 
GrayWidth; likewise for Height and Thresholds. 

Halftone phase 

In a printer, the gray pattern tiles device space starting at the 
device space origin. That is, the halftone grid is aligned such that 
the lower left comer of the lower left halftone cell is positioned 
at (0, 0) in device space, independent of the value of the current 
transformation matrix. This ensures that adjacent gray areas will 
be painted with halftones having the same phase, thereby avoid¬ 
ing ‘seams’ or other artifacts. 

On a display, the phase relationship between the halftone grid 
and device space needs to be more flexible. This need arises be- 


16 that is, the comer corresponding to the minimum x and y coordinates in 
device space; mathematically, this is the ‘lower left’ comer in a normal, 
right-handed Cartesian coordinate system. Display devices typically have a 
left-handed coordinate system in which y coordinates increase downward on 
the screen. For such devices, the mathematical ‘lower left’ comer is the upper 
left comer on the physical screen. 
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cause most window systems provide a scrolling operation in 
which the existing contents of raster memory are copied from 
one place to another in device space. This operation can alter the 
phase of halftones that have already been scan converted. It is 
necessary to alter the phase of the halftone generation algorithm 
correspondingly so that newly painted halftones will align with 
the existing ones. 

The graphics state includes a pair of halftone phase parameters, 
one for x and one for y. These integers define an offset from the 
device space origin to the halftone grid origin. Of course, the 
halftone grid does not actually have an origin, so the offset 
values are actually interpreted modulo the width and height of 
the halftone cell. Effectively, they ensure that some halftone cell 
will have its lower left comer at (x, y) in device space. 

The intended use of the halftone phase operators 
(sethalftonephase and currenthalftonephase) is in conjunction 
with window system operations that perform scrolling. If the ap¬ 
plication scrolls the displayed image by ( dx , dy) pixels in device 
space, it should simply add dx and dy to the halftone phase 
parameters; it should not worry about computing them modulo 
the size of the halftone cell. This has the correct effect even if the 
displayed image is composed of several different halftone 
screens. 

Note that the halftone phase is defined to be part of the graphics 
state, not part of the device. This is because an application may 
subdivide device space into multiple regions that it scrolls in¬ 
dependently. A recommended technique is to associate a 
separate gstate (graphics state) object with each such region; this 
object carries all the parameters required to image within that 
region, including the halftone phase. 


12 SCAN CONVERSION DETAILS 

As discussed in Section 2.3 of the PostScript Language Refer¬ 
ence Manual, the PostScript interpreter executes a scan 
conversion algorithm to render abstract graphical shapes in the 
raster memory of the output device. The details of this algorithm 
have not been specified until now, since they are of little concern 
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to a PostScript language program that purports to be device inde¬ 
pendent. However, at the low resolutions typical of computer 
displays, one must pay some attention to scan conversion details, 
since variations of even one pixel’s width can have a noticeable 
effect on appearance. 

To ensure consistent and predictable results, the scan conversion 
algorithm is now specified more rigorously. This is not a lan¬ 
guage change per se; it is a more precise description of the scan 
conversion process, whose former definition was rather vague. 
Additionally, the PostScript imaging model has been extended to 
include a device-independent means for obtaining consistent line 
widths during stroke operations. 

Scan conversion rules 

The rules below enable one to determine precisely which device 
pixels will be affected by a painting operation. These rules apply 
to the Display PostScript system and to future PostScript 
products from Adobe Systems based on the same software tech¬ 
nology; they do not necessarily apply to older products. 

In the following descriptions, all references to coordinates and 
pixels are in device space. A ‘shape’ is a path to be painted with 
the current color or with an image; its coordinates are mapped 
into device space but not rounded to device pixel boundaries. At 
this level, curves have been flattened to sequences of straight 
lines and all ‘insideness’ computations have been performed. 

Pixel boundaries fall on integer coordinates in device space. A 
pixel is a square region identified by the coordinates of its min¬ 
imum x, minimum y comer. A pixel is a half-open region, mean¬ 
ing that it includes half of its boundary points. More precisely, 
for any point whose real number coordinate is (jc, y), let 
i = floor(x) and j = floor(y). The pixel that contains this point is 
the one identified as (/, j). The region belonging to that pixel is 
defined to be the set of points (x\ y') such that i < x' < i +1 and 
;</</+ 1 . 

Like pixels, shapes to be filled are also treated as half-open 
regions that include the boundaries along their ‘floor’ sides but 
not along their ‘ceiling’ sides. 
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A shape is scan converted by painting any pixel whose square 
region intersects the shape, no matter how small the intersection 
is. This ensures that no shape ever disappears as a result of un¬ 
favorable placement relative to the device pixel grid (as might 
happen with other possible scan conversion rules). The area 
covered by painted pixels is always at least as large as the area of 
the original shape. 

This scan conversion rule applies to both fill operations and to 
strokes with non-zero width. Zero-width strokes are done in a 
device dependent manner that may include fewer pixels than this 
rule specifies. 

The region of device space to be painted by a sampled image is 
determined similarly, though not identically. The image source 
rectangle is transformed into device space and defines a half¬ 
open region, just as for fill operations. However, only those 
pixels whose centers lie within the region are painted. Further¬ 
more, the position of the center of such a pixel (i.e., coordinate 
values whose fractional part is one-half) is mapped back into 
source space to determine how to color the pixel. There is no 
averaging over the pixel area; if the resolution of the source 
image is higher than that of device space, some source samples 
are not be used. 

For clipping, the clip region consists of the set of pixels that 
would be included by a fill. A subsequent painting operation af¬ 
fects a region that is the intersection of the set of pixels defined 
by the clip region with the set of pixels for the region to be 
painted. 

Automatic stroke adjustment 

When a stroke is drawn along a path, the scan conversion 
process may produce lines of non-uniform thickness due to ras¬ 
terization effects. This is because in general the line width and 
the coordinates of the end points, translated into device space, 
are arbitrary real numbers, not quantized to device pixels. Thus, 
a line of a given width can intersect with a different number of 
device pixels depending on where it is positioned. 

For best results, it is important to compensate for the rasteriza- 
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tion effects so as to produce strokes of uniform thickness; this is 
especially important in low-resolution display applications. 
While this can be done explicitly by a PostScript language 
program (as discussed in the documentation for itransform in 
the PostScript Language Reference Manual), doing so is cum¬ 
bersome and inefficient. The newly introduced user path render¬ 
ing operators, such as ustroke, provide no opportunity for a 
program to intervene in order to adjust the coordinates and line 
width. Furthermore, a more sophisticated adjustment algorithm 
is required to produce the most accurate results. 

To meet this need, a stroke adjustment mechanism has been 
introduced as a standard part of the PostScript imaging model. 
When it is in effect, the line width and the coordinates of a stroke 
are automatically adjusted as necessary to produce lines of 
uniform thickness; furthermore, the thickness is as near as pos¬ 
sible to the requested line width (i.e., no more than half a pixel 
different). 17 

Because automatic stroke adjustment can have a substantial ef¬ 
fect on the appearance of lines, an application must be able to 
control whether or not it is performed. The operator 
setstrokeadjust alters a boolean value in the graphics state that 
determines whether or not stroke adjustment will be performed 
during subsequent stroke and related operators. This allows 
compatibility with existing PostScript language programs. 

When a character description is executed (e.g., the BuildChar 
procedure of a user-defined font), stroke adjustment is initially 
disabled instead of being inherited from the context of the show 
operation. This is necessary because character descriptions are 
executed at unpredictable times due to font caching. A 
BuildChar procedure can enable stroke adjustment if it wants to. 


17 If the requested line width, transformed into device space, is less than half a 
pixel, the stroke is rendered as a single-pixel line. This is the thinnest line that 
can be rendered at device resolution; it is equivalent to the effect produced by 
setting the line width to zero. 
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13 VIEW CLIPS 


Interactive applications frequently make incremental updates to 
the displayed image. Such updates arise both from changes to the 
displayed graphical objects themselves and from window system 
manipulations that cause formerly obscured objects to become 
visible. For efficiency’s sake, it is desirable for the application to 
redraw only those graphical objects that are affected by the 
change. 

One approach to accomplishing this is to define a path that 
encloses the changed areas of the display, then redraw only those 
graphical objects that are enclosed (or partially enclosed) within 
the path. To produce correct results, it is necessary to impose this 
path as a clipping path while redrawing. If this were not done, 
portions of objects that are redrawn might incorrectly obscure 
objects that are not redrawn. 

This clipping could be accomplished by adjusting the clipping 
path in the graphics state in the normal way. However, this is not 
particularly convenient, since the program that imposes the clip¬ 
ping and the program that is executed to redraw objects on the 
display may have different ideas about what the clipping path 
should be. This problem becomes particularly acute given the 
ability to switch entire graphics states arbitrarily. 

To alleviate this, we have extended the PostScript imaging 
model to introduce another level of clipping, the view clip , that is 
entirely independent of the graphics state. Objects are rendered 
on the device only in areas that are enclosed by both the current 
clipping path and the current view clipping path. 

The view clipping path is actually part of the PostScript execu¬ 
tion context, not the graphics state. Its initial value is a path that 
encloses the entire imageable area of the output device (see 
initviewclip). The operators that alter the view clipping path do 
not affect the clipping path in the graphics state or vice versa. 
The view clipping path is not affected by gsave and grestore; 
however, a restore will reinstate the view clipping path that was 
in effect at the time of the matching save. 18 Note that view clips 

18 View clipping is temporarily disabled when the current output device is a 
mask device, such as the one installed by setcachedevice. 
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do not nest; rather, a new view clip replaces the existing one. 
The following operators manipulate view clips: viewclip, 
eoviewclip, rectviewclip, v'ewclippath, and initviewclip. 


14 WINDOW SYSTEM SUPPORT 

For each integration of the Display PostScript system with a win¬ 
dow system, there is a collection of operators for doing such 
things as specifying the window that is to be affected by sub¬ 
sequent painting operators. These operators are window system 
specific because their syntax and semantics vary according to the 
properties and capabilities of the underlying window system. 
They are not documented in this manual. 

In addition to the window system specific operators, there are 
several operators that are window related but have a consistent 
meaning across all window systems. They are needed to enable 
an application to associate input events (e.g., mouse clicks) with 
graphical objects in user space. These operators (i.e., infill, 
ineofill, inufill, inueofill. instroke, and inustroke) can be used 
freely by display based applications. 

If a window system specific extension provides a way for a 
PostScript language program to receive input events directly, the 
program can perform operations such as mouse tracking and hit 
detection itself. With some window systems, however, input 
events are always received by the application. In that case, the 
application must either perform such computations itself or issue 
queries to the Display PostScript system. This decision involves 
a tradeoff between performance and application complexity. One 
possible approach is for the application to perform hit detection 
itself for simple shapes but to query the Display PostScript sys¬ 
tem for more complex shapes. 

A program may require information about certain properties of 
the raster output device, such as whether or not it supports color 
and how many distinguishable color or gray values it can 
reproduce. A PostScript language program that is a page descrip¬ 
tion should not need such information; using it compromises 
device independence. However, an interactive application using 
the Display PostScript system may desire to vary its behavior 
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according to the available display technology. For example, a 
CAD application may use stipple patterns on a binary black-and- 
white display but separate colors on a color display. 

The deviceinfo operator returns a dictionary whose entries 
describe static information about the device. (Dynamic informa¬ 
tion must be read from the graphics state or obtained through 
operators such as wtranslation.) Some of the entries in this dic¬ 
tionary have standard names that are described in the table 
below; others may have meanings that are device dependent. 
Most entries are optional and are present only if they are relevant 
for that type of device. 


Key 

Type 

Semantics 

Colors 

integer 

number of independent color components: 1 indicates black-and-white or gray 
scale only; 3 indicates red, green, blue; 4 indicates red, green, blue, gray (or 
their complements: cyan, magenta, yellow, black, as typically used in printers). 

GrayValues 

integer 

number of different gray values that individual pixels can reproduce (without 
halftoning). For example, 2 indicates a binary black-and-white device; 256 
indicates an 8 bits-per-pixel gray scale device. 

RedValues 

integer 

number of different red values that individual pixels can reproduce, inde¬ 
pendent of other colors. 

GreenValues 

integer 

analogous to RedValues. 

BlueValues 

integer 

analogous to RedValues. 

ColorValues 

integer 

total number of different color values that each pixel can reproduce. If this 
entry is present and the entries for gray, red, green, and blue are absent, this 
means that the color components cannot be varied independently but only in 
combination. 


15 MISCELLANEOUS CHANGES 

This section contains miscellaneous language changes that have 
not been documented in earlier sections. 

Additions to statusdict 

As described in the PostScript Language Reference Manual , the 
standard dictionary statusdict is the repository for information 
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and facilities that are specific to individual products. The set of 
keys and values contained in statusdict is product dependent. 
However, every product’s statusdict contains a product 
(product name string) and revision (product revision number). 

In the Display PostScript system, the standard set of statusdict 
entries is extended to include the following: 

Key Type Semantics 


buildtime integer uniquely identifies a specific generation of this product Its main purpose is to 

distinguish among various alpha- and beta-test versions of a product prior to its 
formal release; the value of revision is changed only for formal releases. (The 
integer value of buildtime actually represents a date and time in the format 
used in the machine on which the PostScript interpreter was constructed; this 
meaning, however, is not of any use to a PostScript language program.) 

byteorder boolean describes the native (preferred) order of bytes in multiple-byte numbers appear¬ 

ing in binary tokens and binary object sequences (see Section 2). The value 
false indicates high-order byte first; true indicates low-order byte first. Al¬ 
though the interpreter will accept numbers in either order, it will process 
numbers in native order somewhat more efficiently. 

realformat string identifies the native format for real (floating-point) numbers appearing in 

binary tokens and binary object sequences (see Section 2). If the native format 
is IEEE standard, the value of this string is ‘IEEE’; otherwise, the value 
describes a specific native format, e.g., ‘VAX’. The interpreter will always 
accept real numbers in IEEE format, but it may process numbers in native 
format more efficiently. An application program can query realformat to 
determine whether the interpreter’s native format is the same as the 
application’s; if so, translation to and from IEEE format can be avoided. 


Syntax and scanner changes 

As described in Section 2, the PostScript language syntax has 
been augmented to introduce binary tokens and binary object se¬ 
quences. In the course of altering the PostScript interpreter’s in¬ 
put scanner to accept the augmented language, we have taken the 
opportunity to eliminate several anomalies in the existing scan¬ 
ner. These anomalies are obscure; for some, the PostScript Lan¬ 
guage Reference Manual does not give a clear specification of 
what the correct behavior should be. 

The principal change has to do with execution of string objects. 
A program to be executed by the PostScript interpreter can come 
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from either a file object or a string object. In the normal case, the 
interpreter reads from a file object, such as the one for the stan¬ 
dard input file. However, as described in Section 3.6 of the 
PostScript Language Reference Manual , the interpreter can also 
read from an executable string object; this is accomplished by 
applying exec (or other execution operators) to the string. The 
token operator, which invokes the PostScript language scanner 
only, also accepts a string operand. 

The syntax and semantics of a program should be the same 
whether the program is read from a file or from a string. 
However, in previous versions of the PostScript interpreter, there 
has been one difference in the treatment of string literals, 
enclosed in ‘(’ and *)’, which appear in the program being ex¬ 
ecuted. If the program is read from a file, ‘V (back-slash) escape 
sequences have special meanings (see PostScript Language Ref¬ 
erence Manual, Section 3.3); if the program is read from a string, 
‘V escape sequences are not recognized and the characters are 
treated literally. 

In the Display PostScript system and in future products based on 
the same software technology, this distinction between file and 
string execution semantics is eliminated. ‘V escape sequences are 
now recognized in string literals always, regardless of whether 
the program is being read from a file or a string. 

This change is relatively obscure and is unlikely to affect real 
programs. A contrived example illustrates the effect of the 
change: 

(/a (\\n) def) cvx exec 

When the outer string is scanned, the ‘\V is treated as an escape 
sequence and replaced by a single ‘V; this is true under both old 
and new conventions. The difference lies in what happens when 
the outer string is executed—specifically, in the contents of the 
inner string that is defined to be the value of ‘a’. Under the old 
convention, the ‘V in this string is not recognized as an escape; 
consequently, the string consists of the two characters ‘V and ‘n’. 
Under the new convention, the ‘V is recognized as an escape; the 
resulting string consists of a single newline character produced 
from the escape sequence ‘\n’. 
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Note that escape sequences apply only in ASCII encoded string 
literals. A string appearing in a binary token or binary object 
sequence is always treated literally (see Section 2). The inter¬ 
preter can consume a binary encoded program from a string just 
the same as from a file; the syntax accepted by the interpreter 
does not depend on the source of the characters being inter¬ 
preted. 

Apart from the change in string execution, there are several other 
differences between the scanner in the Display PostScript system 
and that of previous interpreters: 

• Outside of a string literal, the old scanner sometimes treats 
‘V as a self-delimiting special character, depending on con¬ 
text. The new scanner always treats ‘V as a regular char¬ 
acter except within a string literal. This is consistent with 
the language specification. 

• The characters FF (ASCII \014) and NUL (ASCII \000) are 
treated as white space characters. Of these, FF will ter¬ 
minate a comment; NUL will not. This is a documentation 
change; the old and new scanners behave the same in this 
regard. 

• Certain tokens that are syntactically legal numbers but that 
exceed implementation limits are converted to name ob¬ 
jects by the old scanner; the new scanner generates a 
limitcheck error in such cases. 

• With the old scanner, all erroneous radix numbers of the 
form basettnumber are treated as names. With the new 
scanner, a base value not in the range 2 to 36 inclusive or a 
number digit not valid for the base causes the token to be 
treated as a name. However, if the number is syntactically 
valid but is simply too large to represent, a limitcheck oc¬ 
curs. 

File system extensions 

The Display PostScript system optionally provides access to 
named files in secondary storage. The file access capabilities are 
provided as part of the integration of the Display PostScript sys¬ 
tem with an underlying operating system; there are variations 
from one such integration to another. Not all the file system ca¬ 
pabilities of the underlying operating system are necessarily 
made available at the PostScript language level. 
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The PostScript language provides a standard set of operators for 
accessing files. These consist of file, originally described in the 
PostScript Language Reference Manual, and several new 
operators: deletefile, renamefile, filenameforall, 

setfileposition, and fileposition. Although the language defines 
a standard framework for dealing with files, the detailed seman¬ 
tics of the file system operators (particularly file naming 
conventions) are operating system dependent. 

Files are contained within one or more ‘secondary storage 
devices’, hereafter referred to simply as devices (but not to be 
confused with the ‘current device’, which is a display device in 
the graphics state). The PostScript language defines a uniform 
convention for naming devices, but it says nothing about how 
files in a given device are named. Different devices have dif¬ 
ferent properties, and not all devices support all operations. 

A complete file name is in the form ‘%de wce% file' , where 
device identifies the secondary storage device and file is the 
name of the file within the device. When a complete file name is 
presented to a file system operator, the device portion selects the 
device; th efile portion is in turn presented to the implementation 
of that device, which is operating system and environment de¬ 
pendent. 

When a file name is presented without a ‘%dew'ce%’ prefix, a 
search rule determines which device is selected. The available 
storage devices are consulted in order; the requested operation is 
performed for each device until it succeeds. The number of 
available devices, their names, and the order in which they are 
searched is environment dependent. Not all devices necessarily 
participate in such searches; some devices can be accessed only 
by naming them explicitly. 

Normally, there is a device that represents the complete file sys¬ 
tem provided by the underlying operating system. 19 If so, by 
convention that device’s name is ‘os’; thus, complete file names 
are in the form ‘%os %file’, where file conforms to underlying 
file system conventions. This device always participates in 

19 However, this device may impose some restrictions on the set of files that can 
be accessed. The need for restrictions arises when the PostScript interpreter 
executes with a user identity different from that of the user running the appli¬ 
cation program. 
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searches, as described above; thus, a program can access or¬ 
dinary files without specifying the ‘%os%’ prefix. There may be 
more than one device that behaves in this way. 

Additionally, there is normally a device that represents font 
definitions that can be loaded dynamically by the findfont 
operator. If so, by convention that device’s name is ‘font’; thus, 
complete file names are in the form ‘%font%ff/e’ , where file is a 
specific font name such as ‘Palatino-Boldltalic’. Note that this 
naming convention does not necessarily have anything to do 
with how font files are actually named in the underlying operat¬ 
ing system; the ‘font’ device is logically decoupled from the ‘os’ 
device. This device never participates in searches; accessing font 
files requires specifying the ‘%font%’ prefix. If a ‘font’ device 
exists, the built-in definition of findfont will attempt to run the 
named font from that device; the program in the font file should 
create a font dictionary and execute a definefont with the same 
name. 

For the operators file, deletefile, renamefile, status, and 
filenameforall, a filename is a string object that identifies a file. 
The file name can be in one of three forms: 

% device% file identifies a file on a specific device, as described 
above. 

% device identifies one of the special files ‘%stdin’, 

‘%stdout’, ‘%lineedit’, or ‘%statementedit’, 
described in Section 3.8 of the PostScript Lan¬ 
guage Reference Manual. 

file (first character not “%’) identifies a file on an 

unspecified device; the device is selected by an 
environment specific search rule, as described 
above. 

An access is a string object that specifies how a file is to be 
accessed. File access conventions are operating system specific. 
The following access specifications are typical of the UNIX® 
operating system and are supported by many others. The access 
string always begins with ‘r’, ‘w’, or ‘a’, possibly followed by 
V; any additional characters supply operating system specific 
information. 
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r open for reading only; error if file doesn’t already ex¬ 
ist. 

w open for writing only; create file if it doesn’t already 
exists; truncate it if it does. 

a open for writing only; create file if it doesn’t already 
exist; append to it if it does. 

r+ open for reading and writing; error if file doesn’t al¬ 
ready exist. 

w+ open for reading and writing; create file if it doesn’t 
already exist; truncate it if it does. 
a+ open for reading and writing; create file if it doesn’t 
already exist; append to it if it does. 

Timekeeping 

The usertime operator, which is specified as returning execution 
time of the PostScript interpreter, now reports interpretation time 
on behalf of the current context only. The ability to perform per- 
context timekeeping accurately depends on the underlying 
operating system; in some environments, it may not be possible 
to separate execution time of the PostScript interpreter from that 
of other programs executing concurrently. 

A new standard operator, realtime, returns elapsed real time, in¬ 
dependent of the activities of the PostScript interpreter or other 
programs. 

Standard Error Handlers 

As described in Section 3.6 of the PostScript Language Refer¬ 
ence Manual, when an error occurs, the PostScript interpreter 
looks up the error’s name in errordict and executes the associ¬ 
ated procedure. That procedure is expected to handle the error in 
some appropriate way. 

The errordict present in the initial state of the VM provides 
standard handlers for all errors. However, errordict is a writable 
dictionary; a program can therefore replace individual error- 
handlers selectively. Since errordict is in the private VM, such 
changes are visible only to the context that made them (or to 
other contexts sharing the same space). 
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The standard error handlers in the Display PostScript system be¬ 
have slightly differently from the ones described in the 
PostScript Language Reference Manual , Section 3.8. They 
operate as follows: 

• Execute ‘false setshared’, thereby reverting to private VM 
allocation mode 

• Record information about the error in the special diction¬ 
ary, $error; in the Display PostScript system, $error is lo¬ 
cated in private VM. 

• Execute stop, thereby exiting the innermost enclosing con¬ 
text established by stopped. 

The information recorded in the $error dictionary is shown in 
the table in Section 3.8 of the PostScript Language Reference 
Manual. In particular, the entries newerror, errorname, and 
command are always stored. However, the ostack, estack, and 
dstack arrays, which record snapshots of the operand, execution, 
and dictionary stacks, are generated only if the entry 
recordstacks has been previously set to the boolean value true ; 
its normal value is false. 20 

The procedure handleerror is invoked if a program loses control 
due to an error. In the Display PostScript system, the standard 
definition of handleerror generates a special type of binary ob¬ 
ject sequence, not a text message. This is described in Section 3. 

Font Cache Size 

The total size of the font cache can be adjusted dynamically. 
This enables one to tune the amount of memory consumed by the 
font cache according to the needs of applications and output 
devices. With undemanding applications and low-resolution 
devices, a relatively small font cache suffices. When applications 
use many fonts in many sizes or output to high-resolution 
devices, a large font cache is required for good performance. 

Adjusting the font cache size is accomplished by an extension to 
the existing setcacheparams operator, which takes a variable 

20 The error handler for VMerror never snapshots the stacks, regardless of the 
value of recordstacks. This prevents an attempt to allocate more VM at a time 
when VM is already exhausted. 
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number of operands, currentcacheparams returns the font 
cache parameters as described in the PostScript Language Refer¬ 
ence Manual, with the addition of the result size. See the 
operator description in Section 16. 

Permanent Entries on Dictionary Stack 

There are three permanent entries on the dictionary stack for the 
Display PostScript system. In order, starting from the bottom, 
they are: systemdict, shareddict, and userdict. A new operator, 
cleardictstack, has been added so that a program may clear all 
nonpermanent entries from the dictionary stack without having 
to know how many permanent entries there are. 
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16 OPERATORS 


Conventions 

This chapter contains detailed descriptions of all the extensions 
to the PostScript language that implement the Display PostScript 
system. The operators are organized alphabetically by operator 
name. Each operator description is presented in the following 
format: 


operator operand, operand 2 ... operand,, operator result, ... result m 
Detailed explanation of the operator 
EXAMPLE: 

An example of the use of this operator. The symbol *=>’ 
designates values left on the operand stack by the example. 

ERRORS: 

A list of the errors that this operator might execute. 

At the head of an operator description, operand 'j through 
operand n are the operands that the operator requires, with 
operand n being the topmost element on the operand stack. The 
operator pops these objects from the operand stack and con¬ 
sumes them. After executing, the operator leaves the objects 
result j through result m on the stack, with result m being the top¬ 
most element. 

Normally the operand and result names suggest their types. The 
following table lists most of the operand and result names and 
their use. 
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name 


see section description 


filename 

font 

halftone 

int 

matrix 

num 

numstring 

proc 


user path 


15 is a file name string. 

5.3 of PostScript Language Reference Manual 

is a dictionary constructed according to the rule for font dictionaries. 

11 is a dictionary constructed according to the rule for halftone dictionaries. 

3.4 of PostScript Language Reference Manual 

indicates an integer number. 

4.4 of PostScript Language Reference Manual 

is an array of six numbers describing a transformation matrix. 

3.4 of PostScript Language Reference Manual 

indicates that the operand or result is a number (integer or real). 

2 is an encoded number string. 

3.4 of PostScript Language Reference Manual 

indicates a PostScript procedure (i.e., an executable array or executable packed 
array). 

8 is an array of path construction operators and their operands or an array of two 

strings comprising an encoded user path. 


The notation in the operand position indicates that the 
operator expects no operands, and a in the result position 
indicates that the operator returns no results. 

The documented effects on the operand stack and the possible 
errors are those produced directly by the operator itself. Many 
operators cause arbitrary PostScript procedures to be invoked. 
Obviously, such procedures can have arbitrary effects that are 
not mentioned in the operator description. 
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Operator Summary 
Structured Output Operators 


- 

currentobjectformat int 

return binary object format 83 

obj Int 

printobject - 

write binary object to standard output file, 
using int as tag 101 

Int 

setobjectformat - 

set binary object format (0=disable, 1=1 EEE 
high, 2=low, 3=native high, 4=low) 113 

file obj int 

writeobject - 

write binary object to file, using int as 
tag 131 

Memory Management Operators 


- 

currentshared bool 

return current VM allocation mode 84 

key font 

definefont font 

register a font as a font dictionary 84 

any 

scheck bool 

true if any is simple or in shared VM, false 
otherwise 107 

bool 

setshared 

set VM allocation mode (false= private, 
f/i/e=shared 115 

int 

setvmthreshold 

set the allocation threshold for garbage 
collection 117 

diet key 

undef 

remove key and its value from diet 122 

key 

undefinefont - 

remove font definition 123 

int 

vmreclaim 

control garbage collector 129 

- 

vmstatus level used maximum 

report VM status 130 


Multiple Execution Context Operators 


- 

condition condition 

create condition object 81 

- 

currentcontext context 

return current context identifier 82 

context 

detach 

enable context to terminate immediately 
when done 87 

mark obj 1 .. obj n proc 

fork context 

create context executing proc with obj, .. 
obj n as operands 92 

context 

join mark obj 1 .. obj n 

await context termination and return its 
results 98 

- 

lock lock 

create lock object 99 

lock proc 

monitor - 

execute proc while holding lock 99 

condition 

notify 

resume contexts waiting for condition 100 

- 

quit - 

terminates the context 102 

lock condition 

wait - 

release lock , wait for condition, reacquire 
lock 131 

- 

yield 

suspend current context momentarily 133 
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User Object Operators 


- 

UserObjects array 

return UserObjects array in userdict 125 

index any 

defineuserobject - 

associate index with any in UserObjects 
array 86 

index 

execuserobject - 

execute index element in UserObjects 
array 88 

index 

undefineuserobject - 

remove index element from UserObjects 
array 123 

Graphics State Object Operators 


gstate 

currentgstate gstate 

read current graphics state into gstate 82 

- 

gstate gstate 

create graphics state object 93 

gstate 

setg state 

set graphics state from gstate 112 

User Path Operators 


x i yi x 2 y 2 r 

arct - 

append tangent arc 81 

»x "y ur x ur y 

setbbox - 

set bounding box for current path 109 

mark blimit 

setucacheparams - 

set user path cache parameters 116 

userpath 

uappend - 

interpret userpath and append to current 
path 120 

- 

ucache - 

declare that user path is to be cached 121 


ucachestatus mark bsize bmax rsize rmax blimit 

return user path cache status and 
parameters 121 

userpath 

ueofill 

fill using even-odd rule 121 

userpath 

ufill - 

interpret and fill userpath 122 

bool 

upath userpath 

create userpath for current path; include 
ucache if bool is true 124 

userpath 

ustroke - 

interpret and stroke userpath 126 

userpath matrix 

ustroke - 

interpret userpath , concatenate matrix, and 
stroke 126 

userpath 

ustrokepath 

compute outline of stroked userpath 127 

userpath matrix 

ustrokepath 

compute outline of stroked userpath 127 

Rectangle 

Operators 


x y width height 

rectclip - 

clip with rectangular path 103 

numarraylnumstring 

rectclip 

clip with rectangular paths 103 

x y width height 

rectfill - 

fill rectangular path 104 

numarraylnumstring 

rectfill - 

fill rectangular paths 104 

x y width height 

rectstroke - 

stroke rectangular path 105 
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x y width height matrix 

rectstroke 

stroke rectangular path 105 

numarraylnumstring 

rectstroke - 

stroke rectangular paths 105 

numarraylnumstring matrix 

rectstroke 

stroke rectangular paths 105 

Font Operators 


font matrix 

makefont font’ 

produces new font 99 

key scalel matrix 

selectfont - 

set font dictionary given name and 
transform 108 

text numarraylnumstring 

xshow - 

print characters of text using x widths in 
numarraylnumstring 132 

text numarraylnumstring 

xyshow - 

print characters of text using x and y 
widths in numarraylnumstring 133 

text numarraylnumstring 

yshow - 

print characters of text using y widths in 
numarraylnumstring 134 

Halftone Definition Operators 


- 

currenthalftone diet 

return current halftone dictionary 83 

- 

currenthalftonephase x y 

return current halftone phase 83 

- 

currentscreen frequency angle proc 

return current halftone screen 83 

— 

currentscreen 60 0 halftone 

return current halftone dictionary 
(sethalftone was used) 83 

diet 

sethalftone - 

set halftone dictionary 112 

xy 

sethalftonephase - 

set halftone phase 113 

frequency angle proc 

setscreen 

set halftone screen 114 

num 1 num 2 halftone 

setscreen - 

set halftone screen using halftone 
dictionary 114 

Scan Conversion Operators 


- 

currentstrokeadjust bool 

return current stroke adjust 84 

bool 

setstrokeadjust - 

set stroke adjust (/a/se=disable, 
fri/e=enable) 116 

View Clip Operators 


- 

eoviewelip 

view clip using even-odd rule 87 

- 

initviewelip - 

reset view clip 94 

x y width height 

rectviewclip 

set rectangular view clipping path 106 

numarraylnumstring 

rectviewclip 

set rectangular view clipping paths 106 

- 

viewelip 

set view clip from current path 128 

- 

viewelippath 

set current path from view clip 128 
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Window System Support Operators 



deviceinfo diet 

return dictionary containing information 
about current device 87 

xy 

infill bool 

test whether point ( x , y) would be painted 
by fill 94 

userpath 

infill bool 

test whether pixels in userpath would be 
painted by fill 94 

xy 

ineofill bool 

test whether point ( x , y) would be painted 
by eofill 93 

userpath 

ineofill bool 

test whether pixels in userpath would be 
painted by eofill 93 

x y userpath 

inueofill bool 

test whether point (x, y) would be painted 
by ueofill 95 

userpath^ userpath 2 

inueofill bool 

test whether pixels in userpath 1 would be 
painted by ueofill of userpath 2 95 

x y userpath 

inufill bool 

test whether point ( x, y) would be painted 
byufill 96 

userpath 1 userpath 2 

inufill bool 

test whether pixels in userpath 1 would be 
painted by ufill of userpath 2 96 

x y userpath 

inustroke bool 

test whether point ( x , y) would be painted 
by ustroke 97 

x y userpath matrix 

inustroke bool 

test whether point (x, y) would be painted 
by ustroke 97 

userpath 1 userpath 2 

inustroke bool 

test whether pixels in userpath 1 would be 
painted by ustroke of userpath 2 97 

userpath 1 userpath 2 matrix 

inustroke bool 

test whether pixels in userpath 1 would be 
painted by ustroke of userpath 2 97 


wtranslation x y 

return translation from window origin to 
device space origin 132 

File System Operators 


string 

deletefile - 

delete named file 86 

pattern proc scratch 

filenameforall - 

execute proc for each file name matching 
pattern 90 

file 

fiieposition int 

return current position in file 91 

string 1 string 2 

renamefiie 

rename file string 1 to string 2 106 

file int 

setfileposition - 

set file to specified position 112 

string 

status pages bytes referenced created true 


or false 

return information about named file 118 
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Miscellaneous Operators 

cleardictstack - 
currentcacheparams 

index name defineusername 

realtime int 

mark size lower upper setcacheparams - 

usertime int 

Errors 

invalidcontext 

invalidid 


pop all nonpermanent dictionaries off dic¬ 
tionary stack 81 

mark size lower upper 

return current characteristics of font 
cache 82 

define encoded name index 85 
return real time in milliseconds 102 
change characteristics of font cache 111 

return context execution time in 
milliseconds 125 

improper use of context operation 97 

invalid identifier for window-system-specific 
operator 98 
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arct x 1 y 1 x 2 y 2 r arct 

appends an arc of a circle, defined by two tangent lines, to the current 
path. This operator is identical to arcto except that it does not push any 
results on the operand stack, whereas arcto pushes four numbers. That 
is, arct is equivalent to: 

arcto pop pop pop pop 

arct can be used as an element of a user path definition, whereas arcto 
is not allowed. 

ERRORS: 

limitcheck, nocurrentpoint, stackunderflow, typecheck, 
undefinedresult 

cleardictstack - cleardictstack - 

pops all dictionaries off the dictionary stack except for the three per¬ 
manent entries, systemdict, shareddict, and userdict. 

ERRORS: 

(none) 

condition - condition condition 

creates a new condition object, unequal to any condition object already 
in existence, and pushes it on the operand stack. The condition initially 
has no contexts waiting on it. 

Since a condition is a composite object, creating one consumes VM. 
The condition’s value is allocated either in the current context’s space 
(private VM) or in shared VM according to the current VM allocation 
mode (see setshared). 

ERRORS: 

stackoverflow, VMerror 
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copy 


currentcacheparams 


currentcontext 


currentgstate 


gstate 1 gstate 2 copy gstate 2 

copies the value of gstate^ to gstate 2 , entirely replacing gstate 2 s 
former value, then pushes gstate 2 back on the operand stack. (The copy 
operator is thus extended to operate on gstate objects in addition to the 
types it already deals with.) 

ERRORS: 

invalidaccess, stackunderflow, typecheck 


- currentcacheparams mark size lower upper 

pushes a mark object followed by the current cache parameters on the 
operand stack. The number of cache parameters returned is variable 
(see setcacheparams). 

ERRORS: 

stackoverflow 


- currentcontext context 

returns an integer that identifies the current context. 

ERRORS: 

stackoverflow 


gstate currentgstate gstate 

replaces the value of the gstate object by a copy of the current graphics 
state and pushes gstate back on the operand stack. 

If gstate is in shared VM (see Section 4), currentgstate will generate 
an invalidaccess error if any of the composite objects in the current 
graphics state are in private VM. Such objects might include the current 
font, screen function, halftone dictionary, transfer function, or dash 
pattern. In general, allocating gstate objects in shared VM is risky and 
should be avoided. 

ERRORS: 

invalidaccess, stackunderflow, typecheck 


82 


Extensions for the Display PostScript System / Version of January 23,1990 



currenthalftone 


- currenthalftone halftone 


currenthalftonephase 


currentobjectformat 


currentscreen 


If the current halftone was defined by sethalftone or by setscreen 
using a halftone dictionary, currenthalftone returns the current 
halftone dictionary in the graphics state. 

If the current halftone was defined by setscreen using a spot function, 
currenthalftone returns a null object. 

ERRORS: 

stackoverflow 


- currenthalftonephase xy 

returns the current values of the halftone phase parameters in the 
graphics state. If sethalftonephase has not been executed, zero is 
returned for both values. 

ERRORS: 

stackoverflow 


- currentobjectformat int 

returns the current object format parameter (see setobjectformat). 

ERRORS: 

stackoverflow 


- currentscreen frequency angle proc 

- currentscreen 60 0 halftone 

returns the current halftone screen parameters (frequency , angle , and 
proc ) in the graphics state if the current halftone screen was established 
by setscreen. If sethalftone was executed, currentscreen returns a 
frequency of 60, an angle of 0, and the halftone dictionary. (See Sec¬ 
tion 11.) 

ERRORS: 

stackoverflow 
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currentshared 


currentstrokeadjust 


definefont 


- currentshared bool 

returns the current value of the VM allocation mode (see setshared). 

ERRORS: 

stackoverflow 


- currentstrokeadjust bool 

returns the current stroke adjust parameter in the graphics state. 

ERRORS: 

stackoverflow 


key font definefont font 

has its normal effects on FontDirectory and on the font machinery, as 
documented in the PostScript Language Reference Manual. 

Note that FontDirectory normally refers to the font directory in private 
VM; definefont operates only on that directory and not on 
SharedFontDirectory. However, when shared VM allocation mode is 
in effect, the name FontDirectory refers to the font directory in shared 
VM; definefont operates on it. In the latter case, the value of font must 
itself be allocated in shared VM. 

ERRORS: 

dictfull, invalidaccess, invalidfont, stackunderflow, typecheck 
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defineusername index name defineusername - 

establishes an association between the non-negative integer index and 
the name object name in the user name table. Subsequently, the scanner 
will substitute name when it encounters any binary encoded name 
token or object that refers to the specified user name index. (Since 
binary encoded names specify their own literal or executable attributes, 
it does not matter whether name is literal or executable.) 

The user name table is an adjunct to the current context’s private VM 
or space (see Section 5). The effect of adding an entry to the table is 
immediately visible to all contexts that share the same space. Additions 
to the table are not affected by save and restore; the association be¬ 
tween index and name persists for the remaining lifetime of the space. 

The specified index must previously be unused in the name table or 
must already be associated with the same name ; changing an existing 
association is not permitted (an invalidaccess error will occur). There 
may be an implementation limit on index values; assigning index 
values sequentially starting at zero is strongly recommended. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 
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defineuserobject index any defineuserobject - 


establishes an association between the non-negative integer index and 
the object any in the UserObjects array. First, it creates a UserObjects 
array in userdict if one is not already present; it extends an existing 
UserObjects array if necessary. It then executes: 

userdict /UserObjects get 
3 -1 roll put 

In other words, it simply stores any into the array at the position 
specified by index. 

If defineuserobject creates or extends the UserObjects array, it al¬ 
locates the array in private VM regardless of the current VM allocation 
mode. (See Section 6.) 

The behavior of defineuserobject obeys normal PostScript language 
semantics in all respects. In particular, the modification to the 
UserObjects array (and to userdict, if any) is immediately visible to 
all contexts that share the same space. It can be undone by a subsequent 
restore according to the usual VM rules, index values must be within 
the range permitted for arrays; a large index value may cause allocation 
of an array that would exhaust VM resources. Assigning index values 
sequentially starting at zero is strongly recommended. 

ERRORS: 

limitcheck, rangecheck, stackunderflow, typecheck, VMerror 


deletefile filename deletefile - 

removes the specified file from the device. If no such file exists, an 
undefinedfilename error occurs. If this operation is not allowed by the 
device, an invalidfileaccess error occurs. If an environment dependent 
error is detected, an ioerror occurs. 

ERRORS: 

invalidfileaccess, ioerror, stackunderflow, typecheck, 
undefinedfilename 
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detach context detach - 


deviceinfo 


eoviewclip 


specifies that the context identified by the integer context is to ter¬ 
minate immediately when it finishes executing its top-level procedure 
proc y whereas ordinarily it would wait for a join. (If the context is 
already waiting for a join, detach causes it to terminate immediately.) 

detach executes an invalidcontext error if context is not a valid con¬ 
text identifier or if the context has already been joined or detached. It is 
permissible for context to identify the current context. 

ERRORS: 

invalidcontext, stackunderflow, typecheck 


- deviceinfo diet 

returns a read-only dictionary containing static information about the 
current device. The composition of this dictionary varies according to 
the properties of the device; typical entries are given in the table in 
section 14. 

The use of deviceinfo after a setcachedeviceoperation within the scope 
of a BuildChar procedure is not permitted (an undefined error 
results). 

ERRORS: 

stackoverflow 


- eoviewclip 

is similar to viewelip except that it uses the even-odd rule to determine 
the inside of the current path. 

ERRORS: 

limitcheck 
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execuserobject index execuserobject - 


executes the object associated with the non-negative integer index in 
the UserObjects array, execuserobject is equivalent to: 

userdict /UserObjects get 
exch get exec 

execuserobject’ s semantics are similar to those of exec or other ex¬ 
plicit execution operators. That is, if the object is executable, it is 
executed; otherwise, it is pushed on the operand stack. See Section 3.6 
of the PostScript Language Reference Manual. 

If UserObjects is not defined in userdict (because defineuserobject 
has never been executed), an undefined error occurs. If index is not a 
valid index for the existing UserObjects array, a rangecheck error 
occurs. If index is a valid index but defineuserobject has not been 
executed previously for that index, a null object is returned. (See Sec¬ 
tion 6.) 

ERRORS: 

invalidaccess, rangecheck, stackunderflow, typecheck, undefined 
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file filename access file file 

creates a file object for the file identified by filename , accessing it as 
specified by access. The interpretation of the two string operands is 
described in Section 15. See the PostScript Language Reference 
Manual for a description of file objects in general and the file operator 
in particular. 

Once opened, th t file object remains valid until closed or invalidated. It 
can be closed explicitly by closefile or implicitly by reading to end of 
file. It can be invalidated by a restore, by garbage collection, or by 
termination of the current context. 

The lifetime of a file object is based on the VM allocation mode in 
effect at the time the file operator is executed. A restore can destroy a 
file object in private VM but not one in shared VM. 

If the specified filename is malformed or if the file doesn’t exist and 
access does not permit creating a new file, file executes an 
undefinedfilename error. If access is malformed or the requested ac¬ 
cess is not permitted by the device, an invalidfileaccess error occurs. If 
the number of files opened by the current context exceeds an im¬ 
plementation limit, a limitcheck error occurs. If an environment de¬ 
pendent error is detected, an ioerror occurs. 

ERRORS: 

invalidfileaccess, ioerror, limitcheck, stackunderflow, typecheck, 
undefinedfilename 
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filenameforall pattern proc scratch filenameforall - 


enumerates all files whose names match the specified pattern string. 
For each matching file, filenameforall copies the file’s name into the 
supplied scratch string, pushes a string object designating the substring 
of scratch actually used, and calls proc. filenameforall does not return 
any results of its own, but proc may do so. 

The details of pattern matching are device dependent, but the following 
convention is typical. All characters in the pattern are treated literally 
(and are case sensitive), except the following special characters: 

* matches zero or more consecutive characters. 

? matches exactly one character. 

\ causes the next character of the pattern to be treated 
literally, even if it is **’, ‘?’, or ‘V. 

If pattern does not begin with *%’, it is matched against device relative 
file names of all devices in the search order (see the description above). 
When a match occurs, the file name passed to proc is likewise device 
relative, i.e., it does not have a ‘%dewce%’ prefix. 

If pattern does begin with s %\ it is matched against complete file 
names in the form i %device%file > ; pattern matching can be performed 
on the device , the file , or both parts of the name. When a match occurs, 
the file name passed to proc is likewise in the complete form 
io /odevice%file\ 

The order of enumeration is unspecified and device dependent. There 
are no restrictions on what proc can do. However, if proc causes new 
files to be created, it is unspecified whether or not those files will be 
encountered later in the same enumeration. Likewise, the set of file 
names considered for pattern matching is device dependent. For ex¬ 
ample, the ‘font’ device might consider all font names whereas the ‘os’ 
general file system device might consider only names in the current 
working directory. 

ERRORS: 

ioerror, rangecheck, stackoverflow, stackunderflow, typecheck 
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fileposition file fileposition position 


returns the current position in an existing open file. The result is a 
non-negative integer interpreted as number of bytes from the beginning 
of the file. If the file object is not valid or the underlying file is not 
positionable, an ioerror occurs. 

ERRORS: 

ioerror, stackunderflow, typecheck, undefinedfilename 


findfont key findfont font 

obtains a font dictionary, as documented in the PostScript Language 
Reference Manual. It looks for key first in FontDirectory, then in 
SharedFontDirectory; thus, fonts defined in private VM take 
precedence over ones defined in shared VM. Only if key is not present 
in either dictionary does findfont perform its environment dependent 
action to locate the font elsewhere. 

Note that when shared VM allocation mode is in effect, the name 
FontDirectory refers to the font directory in shared VM. In this situa¬ 
tion, findfont looks for key only in the shared font directory. Addition¬ 
ally, any action that findfont takes to obtain a font definition from the 
external environment must cause that definition to be created in shared 
VM. 

In the Display PostScript system, when the font being sought is not 
already present in FontDirectory or SharedFontDirectory, findfont 
attempts to obtain a font definition from the execution environment. If 
this succeeds, the font is loaded into shared VM and defined in 
SharedFontDirectory, regardless of the current VM allocation mode. 
This portion of findfont is approximately equivalent to: 

currentshared 
true setshared 

(%font%name) run % load font into shared VM 

setshared % restore old shared mode 

where name is the text of the requested font name (without leading 7’). 
Since the font definition is shared, it is immediately visible to all con¬ 
texts and it persists until explicitly removed by undefinefont. 

ERRORS: 

invalidfont, stackoverflow, typecheck 
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fork mark obj 1 ... obj n proc fork context 

creates a new context using the same space (private VM) as the current 
context. The new context begins execution concurrent with continued 
execution of the current context; which context executes first is unpre¬ 
dictable. 

The new context’s environment is formed by copying the dictionary 
and graphics state stacks of the current context. The initial operand 
stack consists of obj x through obj n , pushed in the same order ( obj x 
through obj n are objects of any type other than mark), fork consumes 
all operands down to and including the topmost mark. It then pushes an 
integer that uniquely identifies the new context. The forked context 
inherits its object format from the current context; all other miscel¬ 
laneous state variables for the context (see Section 5) are initialized to 
default values. 

When the new context begins execution, it executes the procedure proc. 
If proc runs to completion and returns, the context ordinarily will 
suspend until some other context executes a join on context ',; however, 
if the context has been detached, it will terminate immediately (see join 
and detach). 

If proc executes a stop that causes the execution of proc to end prema¬ 
turely, the context will terminate immediately, proc is effectively called 
as follows: 

proc stopped {handleerror quit} if 
% wait for join or detach 
quit 

In other words, if proc stops due to an error, the context invokes the 
error handler in the usual way to report the error; then it terminates, 
regardless of whether or not it has been detached. 

It is illegal to execute fork if there has been any previous save not yet 
matched by a restore; attempting to do so will cause an invalidcontext 
error. 

ERRORS: 

invalidaccess, invalidcontext, limitcheck, stackunderflow, 
typecheck, unmatchedmark 
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gstate - gstate gstate 


ineofill 


creates a new graphics state object and pushes it on the operand stack. 
Its initial value is a copy of the current graphics state. 

This operator consumes VM; it is the only graphics state operator that 
does so. The gstate is allocated in either private or shared VM accord¬ 
ing to the current VM allocation mode (see Section 4). Allocating a 
gstate in shared VM is risky, for reasons described under 

currentgstate. 

ERRORS: 

invalidaccess, stackoverflow, VMerror 


xy ineofill bool 
userpath ineofill bool 


is similar to infill, but its ‘insideness’ test is based on eofill instead of 

mi. 

ERRORS: 

stackunderflow, typecheck 
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infill 


xy infill bool 
userpath infill bool 


initviewclip 


The first form returns true if the device pixel containing the point (x, y) 
in user space would be painted by a fill of the current path in the 
graphics state; otherwise, it returns false. 

In the second form, the device pixels that would be painted by filling 
the userpath become an ‘aperture.’ This form of the operator returns 
true if any of the pixels in the aperture would be painted by a fill of the 
current path in the graphics state; otherwise, it returns false . 

Both forms of this operator ignore the current clipping path and current 
view clip; that is, they detect a ‘hit’ anywhere within the current path, 
even if filling that path would not mark the current page due to clip¬ 
ping. They do not actually place any marks on the current page, nor do 
they disturb the current path. The following program fragment takes the 
current clipping path into account: 

gsave clippath xy infill grestore 
xy infill and 

ERRORS: 

stackunderflow, typecheck 


- initviewclip - 

replaces the current view clipping path by one that encloses the entire 
imageable area of the output device. (It can enclose a larger area than 
that; the actual size and shape of the initial view clip is device 
dependent.) 

ERRORS: (none) 
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instroke 


xy instroke bool 
userpath instroke bool 


inueofill 


returns true if the device pixel containing the point (x> y) in user space 
would be painted by a stroke of the current path in the graphics state; 
otherwise, it returns false. It does not actually place any marks on the 
current page, nor does it disturb the current path. 

In the second form of the operator, the device pixels that would be 
painted by filling the userpath become an ‘aperture.’ instroke returns 
true if any of the pixels in the aperture would be painted by a stroke of 
the current path in the graphics state; otherwise, it returns false. It does 
not actually place any marks on the current page, not does it disturb the 
current path. 

As with infill, this operator ignores the current clip path and current 
view clip; that is, it detects a ‘hit’ on any pixel that lies beneath a stroke 
drawn along the current path, even if stroking that path would not mark 
the current page due to clipping. 

The shape against which the point (jc, y) or the aperture, userpath , is 
tested is computed according to the current stroke-related parameters in 
the graphics state: line width, line cap, line join, miter limit, and dash 
pattern. It is also affected by the stroke adjust parameter (see Section 
12). If the current line width is zero, the set of pixels considered to be 
part of the stroke is device dependent. 

ERRORS: 

stackunderflow, typecheck 


x y userpath inueofill bool 
userpath 1 userpath 2 inueofill bool 


is similar to inufill, but its ‘insideness’ test is based on ueofill instead 
of ufill. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 
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inufill 


xyuserpath inufill bool 
userpath 1 userpath 2 inufill bool 


returns true if the device pixel containing the point (jc, y) in user space 
would be painted by a ufill of the specified userpath (see Section 8); 
otherwise, it returns false. 

In the second form, the device pixels that would be painted by filling 
userpathj become an ‘aperture.’ inufill returns true if any of the pixels 
in the aperture would be painted by a ufill of userpathj otherwise, it 
returns false . 

This operator does not actually place any marks on the current page, 
nor does it disturb the current path in the graphics state. Except for the 
manner in which the path is specified, inufill behaves the same as 

infill. 

By itself, this operator is seemingly a trivial composition of several 
other operators: 

gsave 

newpath uappend 
Infill 

grestore 

However, when used in conjunction with ucache, it can access the user 
path cache, potentially resulting in improved performance. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 
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inustroke 


invalidcontext 


x y userpath inustroke 
x y userpath matrix inustroke 
userpath 1 userpath 2 inustroke 
userpath 1 userpath 2 matrix inustroke 


bool 

bool 

bool 

bool 


returns true if the device pixel containing the point (x> y) in user space 
would be painted by a ustroke applied to the same operands (see Sec¬ 
tion 8); otherwise it returns false. 

In the second form, inustroke concatenates matrix to the CTM before 
executing ustroke (see ustroke operator). 

In the third and fourth forms, the device pixels that would be painted by 
filling userpathj become an ‘aperture.’ inustroke returns true if any of 
the pixels in the aperture would be painted by a ustroke of userpath 2 \ 
otherwise it returns false. 

This operator does not actually place any marks on the current page, 
nor does it disturb the current path in the graphics state. Except for the 
manner in which the path is specified, inustroke behaves the same as 

instroke. 

As with inufill, if userpath is already present in the user path cache, 
inustroke can take advantage of the cached information to optimize 
execution. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 


(error) 

indicates that an invalid use of the context synchronization facilities has 
been detected. Possible causes include: 

• presenting an invalid context identifier to join or detach; 

• executing monitor on a lock already held by the current context; 

• executing wait on a lock not held by the current context; 

• executing any of several synchronization operators when an un¬ 
matched save is pending if the result would be a deadlock. 

The PostScript interpreter detects only the simplest types of deadlock. 
It is possible to encounter deadlocks for which no invalidcontext error 
is generated. 
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invalidid (error) 


indicates that an invalid identifier has been presented to a window- 
system-specific operator. In each integration of the Display PostScript 
system with a window system, there exists a collection of window- 
system-specific operators. The operands of such operators are usually 
integers that identify windows and other objects that exist outside the 
PostScript language. This error occurs when the operand does not iden¬ 
tify a valid object. It is generated only by window-system-specific 
operators and not by any standard operator. 


join context join markobj 1 ... obj n 

waits for the context identified by the integer context to finish execute 
ing its top-level procedure proc. It then pushes a mark followed by the 
entire contents of that context’s operand stack onto the current 
context’s operand stack. Finally, it causes the other context to ter¬ 
minate. 

The objects obj x through obj n are those left on the operand stack by the 
context that is terminating. Ordinarily there should not be a mark 
among those objects, since its presence might cause confusion in the 
context that executes join. 

If context is not a valid context identifier, perhaps because the context 
has terminated prematurely due to an error, join executes an 
invalidcontext error. This also occurs if the context has already been 
joined or detached, if context identifies the current context, or if the 
context does not share the current context’s space. 

It is illegal to execute join if there has been any previous save not yet 
matched by restore; attempting to do so will cause an invalidcontext 
error. 

ERRORS: 

invalidcontext, stackunderflow, stackoverflow, typecheck 
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lock 


- lock lock 


creates a new lock object, unequal to any lock object already in exist¬ 
ence, and pushes it on the operand stack. The state of the lock is 
initially free. 

Since a lock is a composite object, creating one consumes VM. The 
lock’s value is allocated either in the current context’s space (private 
VM) or in shared VM according to the current VM allocation mode 
(see setshared). 

ERRORS: 

stackoverflow, VMerror 


makefont font matrix makefont font’ 

applies matrix to font producing a new font’ whose characters are trans¬ 
formed by matrix when they are printed as described in the PostScript 
Language Reference Manual. The makefont, scalefont, and selectfont 
operators produce a font dictionary derived from an original font dic¬ 
tionary but with the FontMatrix entry altered. The derived font dic¬ 
tionary is allocated in private or shared VM according to whether the 
original font dictionary is in private or shared VM; this is independent 
of the current VM allocation mode. 

ERRORS: 

stackunderflow, typecheck, VMerror 
monitor lock proc monitor - 

acquires lock , first waiting if necessary for it to become free, then 
executes proc , and finally releases lock again. The release of lock oc¬ 
curs whether proc runs to completion or terminates prematurely for any 
reason. 

If lock is already held by the current context, monitor executes an 
invalidcontext error without disturbing the lock. If the current context 
has previously executed a save not yet matched by a restore and lock is 
already held by another context sharing the same space as the current 
context, an invalidcontext error results. These restrictions prevent the 
most straightforward cases of a context deadlocking with itself. 

ERRORS: 

invalidcontext, stackunderflow, typecheck 
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notify condition notify - 


resumes execution of all contexts (if any) that are suspended in a wait 
for condition . 

Ordinarily, notify should be invoked only within the execution of a 
monitor that references the same lock used in the wait for condition. 
This ensures that notifications cannot be lost due to a race between a 
context executing notify and one executing wait. However, this recom¬ 
mendation is not enforced by the language. 

ERRORS: 

stackunderflow, typecheck 
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printobject objtag printobject - 


writes a binary object sequence to the standard output file. The binary 
object sequence contains a top-level array whose length is one; its 
single element is an encoding of obj. If obj is composite, the binary 
object sequence also includes subsidiary array and string values for the 
components of obj. 

The tag operand, which must be an integer in the range 0 to 255, is 
used to tag the top-level object; it is used as the second character of the 
object’s representation. As discussed in Section 3, tag values 0 through 
249 are available for general use; tag values 250 through 255 are 
reserved for special purposes such as reporting errors. 

The binary object sequence uses the number representation established 
by the most recent execution of setobjectformat. The token type given 
as the first character of the binary object sequence reflects the number 
representation that was used. If the object format parameter has been 
set to zero, printobject executes an undefined error. 

The object obj and its components must be of type null, integer, real, 
name, boolean, string, array, or mark (see Section 2); appearance of an 
object of any other type (including packed array) will result in a 
typecheck error. 

printobject always encodes a name object as a reference to a text name 
in the string value portion of the binary object sequence, never as a 
system or user name index. 

As is the case for all operators that write to files, the output produced 
by printobject may accumulate in a buffer instead of being transmitted 
immediately. To ensure immediate transmission, a flush is required. 
This is particularly important in situations where the output produced 
by printobject is the response to a query from the application. 

ERRORS: 

invalidaccess, ioerror, limitcheck, rangecheck, stackunderflow, 
typecheck, undefined 
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quit - quit - 

causes termination of the execution context that issued the quit 
operator. A snaphot VM file is not produced, even on computers with 
operating systems and file systems. (This differs from the description in 
the PostScript Language Reference Manual , where the quit operator 
terminates the PostScript interpreter.) 

Instead of waiting for the join operator to be executed, the context 
terminates immediately as if the detach operator had been executed. 
Any context attempting to join a context that has executed quit will 
receive an invalidcontext error. 

ERRORS: 

(none) 

realtime - realtime int 

returns the value of a clock that counts in real time, independent of the 
execution of the PostScript interpreter. The clock’s starting value is 
arbitrary; it has no defined meaning in terms of calendar time. The unit 
of time represented by the realtime value is one millisecond; however, 
the rate at which it actually changes is implementation dependent. 

ERRORS: 

stackoverflow 
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rectclip x y width height rectclip - 
numarray rectclip - 
numstring rectclip - 


intersects the inside of the current clipping path with a path described 
by the operands. In the first form, the operands are four numbers that 
describe a single rectangle. In the other two forms, the operand is an 
array or an encoded number string that describes an arbitrary number of 
rectangles. After computing the new clipping path, rectclip resets the 
current path to empty, as if by newpath. 

In the first form, assuming width and height are positive, rectclip is 
equivalent to: 

newpath 
xy mo veto 
width 0 rlineto 
0 height rlineto 
width neg 0 rlineto 
closepath 
clip 

newpath 

Note that if the second or third form is used to specify multiple rec¬ 
tangles, the rectangles are treated together as a single path and used for 
a single clip operation. Thus, the ‘inside’ of this combined path is the 
union of all the rectangular subpaths, since the paths are all drawn in 
the same direction and the non-zero winding number rule is used. 

ERRORS: 

limitcheck, stackunderflow, typecheck 
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rectfill x y width height rectfill - 
numarray rectfill - 
numstring rectfill - 


fills a path consisting of one or more rectangles described by the 
operands. In the first form, the operands are four numbers that describe 
a single rectangle. In the other two forms, the operand is an array or an 
encoded number string that describes an arbitrary number of rectangles, 
rectfill neither reads nor alters the current path in the graphics state. 

In the first form, assuming width and height are positive, rectfill is 
equivalent to: 

gsave 
newpath 
xy moveto 
width 0 rlineto 
0 height rlineto 
width neg 0 rlineto 
closepath 
fill 

grestore 

ERRORS: 

stackunderflow, typecheck 
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rectstroke 


x y width height rectstroke - 
x y width height matrix rectstroke - 
numarray rectstroke - 
numarray matrix rectstroke - 
numstring rectstroke - 
numstring matrix rectstroke - 


strokes a path consisting of one or more rectangles described by the 
operands. In the first two forms, the operands are four numbers that 
describe a single rectangle. In the remaining forms, the operand is an 
array or an encoded number string that describes an arbitrary number of 
rectangles. In any event, if the matrix operand is present, rectstroke 
appends it to the CTM before stroking the path. Thus the matrix applies 
to the line width and dash pattern (if any), but not to the path itself, 
rectstroke neither reads nor alters the current path in the graphics state. 

The following example of rectstroke, using x y width height and 
matrix , is equivalent to: 

gsave 
newpath 
xy mo veto 
width 0 rlineto 
0 height rlineto 
width neg 0 rlineto 
closepath 

matrix concat % only if matrix operand is present 

stroke 

grestore 

ERRORS: 

limitcheck, stackunderflow, typecheck 
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rectviewclip x y width height rectviewclip - 
numarray rectviewclip - 
numstring rectviewclip - 


renamefile 


replaces the current view clip by a rectangular path described by the 
operands (see Section 9). In the first form, the operands are four num¬ 
bers that describe a single rectangle. In the other two forms, the 
operand is an array or an encoded number string that describes an 
arbitrary number of rectangles. After computing the new view clipping 
path, rectviewclip resets the current path to empty, as if by newpath. 

Except for the manner in which the path is defined, rectviewclip be¬ 
haves the same as viewclip. 

Note that if the second or third form is used to specify multiple rec¬ 
tangles, the rectangles are treated together as a single path and used for 
a single viewclip operation. Thus, the ‘inside’ of this combined path is 
the union of all the rectangular subpaths, since the paths are all drawn 
in the same direction and the non-zero winding number rule is used. 

ERRORS: 

stackunderflow, typecheck 


old new renamefile - 

changes the name of a file from old to new, where old and new are 
strings that specify file names on the same device. If a file named old 
does not exist, an undefinedfilename error occurs. If a renaming 
operation is not allowed by the device, an invalidfileaccess error oc¬ 
curs. If an environment dependent error is detected, an ioerror occurs. 
Whether or not an error occurs if a file named new already exists is 
environment dependent. 

ERRORS: 

invalidfileaccess, ioerror, stackunderflow, typecheck, 
undefinedfilename 
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scheck 


any scheck bool 


returns true if the operand is simple or if its value is located in shared 
VM, false otherwise. In other words, scheck returns true if one could 
legally store its operand as an element of a shared object. 

ERRORS: 

stackunderflow 
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selectfont 


key scale selectfont - 
key matrix selectfont - 


obtains a font whose name is key , transforms it according to scale or 
matrix , and establishes it as the current font dictionary in the graphics 
state, selectfont is equivalent to one of the following, according to 
whether the second operand is a number or a matrix: 

exch findfont exch scalefont setfont 
exch findfont exch makefont setfont 

If key is present in FontDirectory, selectfont obtains the font diction¬ 
ary directly and does not call the findfont procedure. However, if key is 
not present, selectfont invokes Findfont in the normal way. In the latter 
case, it actually executes the name object ‘findfont’, so it uses the cur¬ 
rent definition of that name in the context of the dictionary stack. (On 
the other hand, redefining exch, scalefont, makefont, or setfont would 
not alter the behavior of selectfont.) 

In the Display PostScript system, fonts can be defined in either 

FontDirectory or SharedFontDirectory (see Section 4). selectfont 
looks in both of those places before calling findfont. 

selectfont can give rise to any of the errors possible for the component 
operations, including arbitrary errors from a user-defined findfont pro¬ 
cedure. 

EXAMPLE: 

/Helvetica 10 selectfont 
/Helvetica findfont 10 scalefont setfont 

The two lines of the example have the same effect, but the first one is 
almost always more efficient. 

In a program represented using the binary token or binary object se¬ 
quence encoding (see Section 2), it may be advantageous to predefine 
key in the user name table so that it can be referenced by a user name 
index instead of a name string. 

ERRORS: 

invalidfont, rangecheck, stackunderflow, typecheck 
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setbbox ll x ll y ur x ur y setbbox - 

establishes an explicit bounding box for the current path. The bounding 
box established by setbbox is the smallest rectangle that contains both 
the existing bounding box, if any, and the bounding box requested by 
the setbbox arguments. These arguments define a rectangle expressed 
as two pairs of coordinates in user space, oriented with the user-space 
coordinate-system axes: ll x and ll y specify the lower left comer; ur x and 
ur y specify the upper right comer. The upper right coordinate values 
must be greater than or equal to the lower left values; otherwise a 
rangecheck error will occur. 

The coordinates of all subsequent path construction operators must fall 
within the resulting bounding box. This bounding box remains in effect 
for the lifetime of the current path — that is, until the next newpath or 
operator that resets the path implicitly, such as stroke, is executed — 
or until it is enlarged by a subsequent setbbox. 

Once setbbox is executed, an attempt to append a path element with a 
coordinate lying outside the bounding box will give rise to a 
rangecheck error. 21 Bounds checking applies only to the path itself, 
not to the result of rendering the path. For example, stroking the path 
may place marks outside the bounding box; this does not cause an 
error. 

Although the setbbox operator can be used when defining any path, its 
main use is in the definition of a user path, where it is mandatory. That 
is, a user path passed to one of the user-path-rendering operators, such 
as ufill, must begin with a setbbox (optionally preceded by a ucache). 
The information passed to setbbox enables the user-path-rendering 
operator to optimize execution. The user path may contain only one 
setbbox. However, multiple executions of uappend during the con¬ 
struction of a current path will result in multiple executions of the 
setbbox operator. In this case, each execution of setbbox has the 
potential to enlarge the bounding box. 

When a path is constructed without an explicit setbbox request, an 
implicit bounding box for the path is maintained dynamically. Each 
path construction operator (moveto, lineto, curveto, and so on) en¬ 
larges the bounding box as necessary to enclose the elements being 
appended to the path. In this case the rangecheck error is not raised 
because the implicit bounding box is automatically adjusted to accom¬ 
modate the growing path. If setbbox is executed when such a path 

21 Note that arcs are converted to sequences of curveto operations. The coordi¬ 
nates computed as control points for those curvetos must also fall within the 
bounding box. Effectively, this means that the figure of the arc must be entirely 
enclosed by the bounding box. 
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exists, the resulting bounding box is enlarged if necessary to enclose 
the implicit bounding box of the path. 

If a bounding box has been established by setbbox, execution of 
pathbbox returns a result derived from that bounding box instead of 
from the implicit bounding box of the path. 

ERRORS: 

rangecheck, stackunderflow, typecheck 
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setcacheparams mark size lower upper setcacheparams - 

sets cache parameters as specified by the integer objects above the 
topmost mark on the stack, then removes all operands and the mark 
object as if by cleartomark. 

The number of cache parameters is variable. 22 If more operands are 
supplied to setcacheparams than are needed, the topmost ones are 
used and the remainder ignored; if fewer are supplied than are needed, 
setcacheparams implicitly inserts default values between the mark and 
the first supplied operand. 

The upper operand specifies the maximum number of bytes that may 
be occupied by the pixel array of a single cached character, as deter¬ 
mined from the information presented by the setcachedevice operator. 
This is the same parameter as is set by setcachelimit; see the descrip¬ 
tion of that operator in the PostScript Language Reference Manual. 

The lower operand specifies the threshold at which characters may be 
stored in compressed form rather than as full pixel arrays. If a 
character’s pixel array requires more than lower bytes to represent, it 
may be compressed in the cache and reconstituted from the compressed 
representation each time it is needed. Some devices do not support 
compression of characters. 

Setting lower to zero forces all characters to be compressed, permitting 
more characters to be stored in the cache but increasing the work re¬ 
quired to print them. Setting lower to a value greater than or equal to 
upper disables compression altogether. 

The size operand specifies the new size of the font cache in bytes (the 
bsize value returned by cachestatus). If size is not specified, the font 
cache size is unchanged. If size lies outside the range of font cache 
sizes permitted by the implementation, the nearest permissible size is 
substituted, with no error indication. Reducing the font cache size can 
cause some existing cached characters to be discarded, increasing ex¬ 
ecution time when those characters are next shown. 

ERRORS: 

limitcheck, rangecheck, typecheck, unmatchedmark 


22 In future versions of the PostScript interpreter there may be more than three 
cache parameters defined. 
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setfileposition file position setfileposition - 


repositions an existing open file to a new position , such that the next 
read or write operation will commence at that position. The position 
operand is a non-negative integer interpreted as number of bytes from 
the beginning of the file. For an output file, setfileposition first per¬ 
forms an implicit flushfile. 

The result of positioning beyond the existing end of file depends on the 
behavior of the underlying file system. 

Possible causes of an ioerror are: the file object is not valid; the under¬ 
lying file is not positionable; the specified position is invalid for the 
file; a device dependent error condition is detected. 

ERRORS: 

ioerror, stackunderflow, typecheck, undefinedfilename 


setgstate gstate setgstate - 

replaces the current graphics state by the value of the gstate object. 
This is a copying operation, so subsequent modifications to the value of 
gstate will not affect the current graphics state or vice versa. Note that 
this is a wholesale replacement of all components of the graphics state; 
in particular, the current clipping path is replaced by the value in gstate , 
not intersected with it. 

ERRORS: 

invalidaccess, stackunderflow, typecheck, undefined 

sethalftone halftone sethalftone - 

establishes halftone as the current halftone dictionary in the graphics 
state. This must be a dictionary constructed according to the rules in 
Section 11. If halftone is a null object instead of a dictionary, 
sethalftone substitutes the default halftone definition for the current 
device (however it was defined). If the halftone dictionary’s 
HalftoneType value is out of bounds or is not supported by the 
PostScript interpreter, a rangecheck error occurs. If a required entry is 
missing or its value is of the wrong type, a typecheck error occurs. If 
the Frequency entry in the halftone dictionary is less than or equal to 
zero, an undefinedresult error occurs. 

ERRORS: 

limitcheck, rangecheck, stackunderflow, typecheck, 
undefinedresult 
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sethalftonephase xy sethalftonephase - 


sets the current halftone phase parameters in the graphics state, x and y 
are integers specifying the new halftone phase, interpreted in device 
space. 

ERRORS: 

stackunderflow, typecheck 


setobjectformat int setobjectformat - 

establishes the number representation to be used in object sequences 
written by subsequent execution of printobject and writeobject. Out¬ 
put produced by those operators will have a token type that identifies 
the representation used. The int operand is one of the following (see 
Section 2): 

0 disable binary encodings (see below) 

1 high-order byte first; IEEE standard real format 

2 low-order byte first; IEEE standard real format 

3 high-order byte first; native real format 

4 low-order byte first; native real format 

Note that any of the latter four values specifies the number represen¬ 
tation only for output. Incoming binary encoded numbers use a repre¬ 
sentation that is specified as part of each token (in the initial token type 
character). 

The value 0 disables all binary encodings for both input and output. 
That is, the PostScript language scanner treats all incoming characters 
as part of the ascii encoding, even if a token starts with a character 
code in the range 128 to 159. The printobject and writeobject 
operators are disabled; executing them will cause an undefined error. 
This mode is provided for compatibility with certain existing PostScript 
language programs. 

Each PostScript execution context has its own object format parameter; 
modifications to this parameter obey the normal save/restore dis¬ 
cipline. When a context is created by fork, the new context inherits its 
object format from the current context. For other contexts, the initial 
value of of the object format parameter is implementation dependent; 
the program must execute setobjectformat in order to generate output 
with a predictable number representation. 

ERRORS: 

rangecheck, stackunderflow, typecheck 
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setscreen frequency angle proc setscreen - 
num 1 num 2 halftone setscreen - 

sets the current halftone screen definition in the graphics state, as 
described in the PostScript Language Reference Manual 

For compatibility with existing applications, setscreen has been ex¬ 
tended to take a halftone dictionary instead of the proc defining the 
spot function (see Section 11). In this case, the nunij and num 2 
operands are ignored. 

ERRORS: 

limitcheck, rangecheck, stackunderflow, typecheck 
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setshared bool setshared - 


changes the VM allocation mode. The value false denotes private VM 
allocation; true denotes shared VM allocation. 

In the normal private VM allocation mode, the values of new com¬ 
posite objects are allocated in the execution context’s private VM. This 
applies both to objects created implicitly by the scanner and ones 
created explicitly by PostScript operators. Private objects cannot be 
stored as components of shared objects. 

In shared VM allocation mode, the values of new composite objects are 
allocated in shared VM. Such objects may be stored as components of 
other shared objects (e.g., shareddict, SharedFontDirectory), thereby 
becoming visible to all contexts. 

Creation and modification of shared objects is unaffected by the 
save/restore facility, whose actions are confined to the private VM of 
the context that executes them. Note that this selective disabling of 
save/restore semantics is based on where each object’s value is lo¬ 
cated; it has nothing to do with the VM allocation mode in effect at the 
time of the save or the restore. 

While shared VM allocation mode is in effect, the name 
FontDirectory refers to the value of SharedFontDirectory, located in 
shared VM, instead of to the normal private font directory. This affects 
the behavior of the definefont and undefinefont operators and the 
findfont procedure. 

The standard error handlers in errordict execute ‘false setshared’, thus 
reverting to private allocation mode if an error occurs. 

ERRORS: 

stackunderflow, typecheck 
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setstrokeadjust bool setstrokeadjust - 


sets the stroke adjust parameter in the current graphics state to bool . If 
bool is true , automatic stroke adjustment will be performed during 
subsequent execution of stroke and related operators (including 
strokepath; see Section 12). If bool is false, stroke adjustment will not 
be performed. 

The initial value of the stroke adjustment parameter is device depend¬ 
ent; typically it is true for displays and false for printers. It is not 
altered by initgraphics. 

ERRORS: 

stackunderflow, typecheck 


setucacheparams markblimit setucacheparams - 

sets user path cache parameters as specified by the integer objects 
above the topmost mark on the stack, then removes all operands and 
the mark object as if by cleartomark. The number of cache parameters 
is variable and may increase in future versions of the PostScript inter¬ 
preter. If more operands are supplied to setucacheparams than are 
needed, the topmost ones are used and the remainder ignored; if too 
few are supplied, setucacheparams implicitly inserts default values 
between the mark and the first supplied operand. 

blimit specifies the maximum number of bytes that can be occupied by 
the reduced representation of a single path in the user path cache. Any 
reduced path larger than this is not saved in the cache. Changing blimit 
does not disturb any paths that are already in the cache. (A blimit value 
that is too large is automatically reduced to the maximum permissible 
value without error indication.) 

ERRORS: 

typecheck, unmatchedmark 
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setvmthreshold int setvmthreshold - 


sets the allocation threshold to the specified value. The allocation 
threshold for a VM is the amount of memory use that will trigger 
automatic garbage collection for that VM (if automatic garbage collec¬ 
tion is enabled; see vmreclaim). The system keeps a separate account¬ 
ing of memory used by each VM. 

The allocation threshold for a VM defaults to a system-specific value. 
The value for a private VM can be changed; the new value must fall 
within the limits of a system-defined minimum and maximum (see 
example below). The value for the shared VM cannot be changed. 
When the allocation threshold for a private VM is exceeded, automatic 
garbage collection is triggered for that VM. When the allocation 
threshold for shared VM is exceeded, automatic garbage collection is 
triggered for the shared VM. 

This operation applies only to the VM of the current context. If the 
specified value is less than the implementation-dependent minimum 
value, the threshold is set to that minimum value. If the specified value 
is greater than the implementation-dependent maximum value, the 
threshold is set to that maximum value. If the value specified is -1, 
then the threshold is set to the implementation dependent default value. 
All the other negative values result in a rangecheck error. 

setvmthreshold never affects the allocation threshold associated with 
shared VM. 


Example: Assuming a default threshold of 40,000, a minimum allow¬ 
able value of 10,000, and a maximum allowable value of 500,000, the 
operation in the first column below produces the result shown in the 
second column. 


20000 setvmthreshold 
-1 setvmthreshold 
20 setvmthreshold 
1000000 setvmthreshold 
-5 setvmthreshold 


Threshold set to 20,000. 
Threshold set to 40,000. 
Threshold set to 10,000. 
Threshold set to 500,000. 
rangecheck error. 


ERRORS: 

rangecheck 
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status 


file status bool 

string status if found pages bytes referenced created true 
if not found false 


If the operand is a file object, status returns true if it is still valid (i.e., 
is associated with an open fil q), false otherwise. This behavior of status 
is as described in the PostScript Language Reference Manual. 

If the operand is a string, status treats it as a file name according to the 
conventions described above. If there exists a file by that name, status 
pushes four integers of status information followed by the value true ; 
otherwise it pushes false. The four integer values are: 


pages 


bytes 

referenced 


created 


storage space actually occupied by the file, in im¬ 
plementation dependent units. 

length of file in characters. 

date and time at which the file was last referenced for 
either reading or writing. The interpretation of the 
value is according to the conventions of the under¬ 
lying operating system; the only assumption that a 
program can make is that larger values indicate later 
times. 

date and time at which the information in the file was 
created. 


ERRORS: 

stackoverflow, stackunderflow, typecheck 
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type any type name 


returns a name object that identifies the type of the object any , as 
documented in the PostScript Language Reference Manual. The type 
operator is extended to operate on gstate, lock, and condition objects in 
addition to the types it already deals with. The possible names that type 
can return are now as follows 

arraytype 
booleantype 
conditiontype 
dicttype 
filetype 
fonttype 
gstatetype 
integertype 
locktype 

ERRORS: 
stackunderflow 


marktype 

nametype 

nulltype 

operatortype 

packedarraytype 

realtype 

savetype 

stringtype 
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uappend userpath uappend - 


interprets a user path definition and appends the result to the current 
path in the graphics state. If userpath is an ordinary user path (i.e., an 
array or packed array whose length is at least 5), uappend is equivalent 
to: 


systemdict begin % ensure standard operator meanings 

cvx exec % interpret userpath 

end 

If userpath is an encoded user path, uappend interprets it and performs 
the encoded operations. It does not matter whether the userpath object 
is literal or executable. 

Note that uappend uses the standard definitions of all operator names 
mentioned in the user path, unaffected by any name redefinition that 
may have occurred. 

A ucache appearing in userpath may or may not have an effect, 
depending on the context in which uappend is executed. If the current 
path is initially empty and no path construction operators are executed 
after uappend, a subsequent rendering operator may access the user 
path cache; otherwise it definitely will not. This is particularly useful in 
the case of clip and viewclip. 

uappend performs a temporary adjustment to the current transfor¬ 
mation matrix as part of its execution. This adjustment consists of 
rounding the t x and t y components of the CTM to the nearest integer 
values. The reason for this is discussed in Section 8. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 
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ucache - ucache - 


notifies the PostScript interpreter that the user path in which the ucache 
operator appears is to be placed in the cache if it is not already there. If 
present, this operator must appear as the first element of a user path 
definition (before the mandatory setbbox). 

The ucache operator has no effect of its own when executed; if ex¬ 
ecuted outside a user path definition, it does nothing. It is useful only in 
conjunction with a user path rendering operator, such as ufill or 
ustroke, that takes the user path as an operand. If the user path is not 
already in the cache, the rendering operator performs the path construc¬ 
tion operations specified in the user path and places the results (referred 
to as the reduced path) in the cache. If the user path is already present 
in the cache, the rendering operator does not interpret the user path but 
obtains the reduced path from the cache. 

ERRORS: (none) 


ucachestatus - ucachestatus mark bsize bmax rsize rmax blimit 

reports the current consumption and limit for two user path cache 
resources: bytes of reduced path storage (bsize and bmax) and total 
number of cached reduced paths (rsize and rmax). Additionally, it 
reports the limit on the number of bytes occupied by a single reduced 
path ( blimit )—reduced paths that are larger than this are not cached. 
All ucachestatus results except blimit are for information only; a 
PostScript language program can change blimit (see 
setucacheparams). 

The number of values pushed on the operand stack is variable; future 
versions of the PostScript interpreter can push additional values be¬ 
tween mark and bsize. The purpose of the mark is to delimit the values 
returned by ucachestatus; this enables a program to determine how 
many values were returned (by counttomark) and to discard any 
unused ones (by cleartomark). 

ERRORS: 

stackoverflow 


ueofill userpath ueofill - 

is similar to ufill, but does eofill instead of fill. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 
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ufill userpath ufill - 


interprets a user path definition and fills the resulting path as if by fill. 
The entire operation is effectively enclosed by gsave and grestore, so 
ufill has no lasting effect on the graphics state, ufill is equivalent to: 

gsave 

newpath 

uappend 

fill 

grestore 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 


undef diet key undef - 

removes key and its associated value from the dictionary diet, diet does 
not need to be on the dictionary stack. 

Note that the effect of undef can be undone by a subsequent restore. 
That is, if key was present in diet at the time of the matching save, 
restore will reinstate key and its former value. (Remember, however, 
that restore has no effect if diet is in shared VM; in that case, the effect 
of undef is permanent.) 

An undef on a dictionary inside a ‘forall’ on that dictionary will give 
undefined results. The following example does not delete all keys in the 
dictionary: 

mydict { pop mydict exch undef} forall 

The dictionary must first be enumerated into another object and that 
object must be enumerated to remove the keys: 

[ mydict { pop } forall ] { mydict exch undef} forall 

Note that this technique is more memory-efficient than assigning a new 
dictionary to ‘mydict’. 

ERRORS: 

invalidaccess, stackunderflow, typecheck, undefined 
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undefinefont key undefinefont - 


removes key and its associated value (a font dictionary) from the 
FontDirectory dictionary. The effect of this is similar to undef; a 
special operator is needed because FontDirectory is read-only. 

Note that FontDirectory normally refers to the font directory in private 
VM; undefinefont operates only on that directory and not on 
SharedFontDirectory. However, when shared VM allocation mode is 
in effect, the name FontDirectory refers to the font directory in shared 
VM; undefinefont operates on it. 

ERRORS: 

stackunderflow, typecheck, undefined 


undefineuserobject index undefineuserobject - 

breaks the association between the non-negative integer index and an 
object established by some previous execution of defineuserobject. It 
does so simply by replacing the specified UserObjects array element 
by the null object; this is equivalent to: 

userdict /UserObjects get 
exch null put 

undefineuserobject does not take any other actions such as shrinking 
the UserObjects array. If index is not a valid index for the existing 
UserObjects array, a rangecheck error occurs. 

There is no need to execute undefineuserobject prior to executing a 
defineuserobject that reuses the same index. The purpose of 
undefineuserobject is to eliminate references to objects that are no 
longer needed. This may enable such objects to be reclaimed by the 
garbage collector. 

ERRORS: 

rangecheck, stackunderflow, typecheck 
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upath bool upath userpath 


creates a new user path object that is equivalent to the current path in 
the graphics state, upath creates a new executable array object of the 
appropriate length and fills it with the operands and operators needed to 
describe the current path, upath produces only an ordinary user path 
procedure, not an encoded user path. It does not disturb the current path 
in the graphics state. 

The bool operand determines whether or not the resulting user path is 
to include ucache as its first element. 

Since the current path’s coordinates are maintained in device space, 
upath transforms them to user space using the inverse of the CTM 
while constructing the user path. Applying uappend to the resulting 
user path will reproduce the same current path in the graphics state, but 
only if the same CTM is in effect at that time. 

upath is equivalent to: 23 

[ 

exch {/ucache cvx} if 

pathbbOX /SGtbbOX CVX 

{/moveto cvx} {/lineto cvx} {/curveto cvx} 

{/closepath cvx} pathforall 
] cvx 

If charpath was used to construct any portion of the current path, 
upath is not allowed; its execution will produce an invalidaccess error. 

ERRORS: 

invalidaccess, stackunderflow, typecheck, VMerror 


23 A perfect emulation of upath may need to be more complex than this in 
order to avoid exceeding the implementation limit on depth of the operand 
stack. 
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UserObjects - UserObjects array 


usertime 


returns the current UserObjects array defined in userdict. 
UserObjects is not an operator; it is simply a name associated with an 
array in userdict. This array is created and managed by the operators 
defineuserobject, undefineuserobjects, and execuserobject. It 
defines a mapping from small integers (used as array indices) to ar¬ 
bitrary objects (the elements of the array). 

The UserObjects entry in userdict is present only if defineuserobject 
has been executed at least once by the current context (or a context that 
shares the same space). The length of the array depends on the index 
operands of all previous executions of defineuserobject. 

Note that defineuserobject, undefineuserobjects, and execuserobject 
operate on the value of UserObjects in userdict, without regard to the 
dictionaries currently on the dictionary stack. Defining UserObjects in 
some other dictionary on the dictionary stack changes the value 
returned by executing the name object UserObjects but does not alter 
the behavior of the user object operators. 

Although UserObjects is an ordinary array object, it should be 
manipulated only by the user object operators. Improper direct altera¬ 
tion of UserObjects can subsequently cause the user object operators 
to malfunction. 

ERRORS: 

stackoverflow, undefined 


- usertime int 

returns PostScript interpreter execution time, as described in the 
PostScript Language Reference Manual. In a Display PostScript sys¬ 
tem that supports multiple execution contexts, the value returned by 
usertime reports execution time on behalf of the current context 
only. 24 As before, the value has no defined starting point, so usertime 
is useful only for interval timing. 

ERRORS: 

stackoverflow 


24 A context that executes usertime can subsequently execute with reduced 
efficiency, because in order to perform user time accounting, the PostScript 
interpreter must perform an operating system call whenever it switches control 
to and from that context. Therefore, one should not execute usertime 
gratuitously. 


16 OPERATORS 


125 



ustroke 


userpath ustroke - 
userpath matrix ustroke - 


interprets a user path definition and strokes the resulting path as if by 
stroke. The entire operation is effectively enclosed by gsave and 
grestore, so ustroke has no lasting effect on the graphics state. 

In the first form (with no matrix operand), ustroke is equivalent to: 

gsave 

newpath 

uappend 

stroke 

grestore 

In the second form, ustroke concatenates matrix to the CTM before 
executing stroke. Thus the matrix applies to the line width and the dash 
pattern (if any) but not to the path itself. This form of ustroke is 
equivalent to: 

gsave 
newpath 
exch uappend 
concat 
stroke 
grestore 

The main use of this operation is to compensate for variations in line 
width and dash pattern that occur if the CTM has been scaled by dif¬ 
ferent amounts in x and y. This is accomplished by defining matrix to 
be the inverse of the unequal scaling transformation. 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 


% interpret userpath 
% concat matrix to CTM 
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ustrokepath 


userpath ustrokepath - 
userpath matrix ustrokepath - 


replaces the current path with one enclosing the shape that would result 
if the ustroke operator were applied to the same operands. The path 
resulting from ustrokepath is suitable as the implicit operand to a 
subsequent fill, clip, or pathbbox. In general, this path is not suitable 
for stroke, as it may contain interior segments or disconnected sub¬ 
paths produced by ustrokepath’s stroke to outline conversion process. 

In the first form, ustrokepath is equivalent to: 

newpath 

uappend 

strokepath 

In the second form, ustrokepath is equivalent to: 25 

newpath 
exch uappend 
matrix currentmatrix 
exch concat 
strokepath 
setmatrix 

ERRORS: 

invalidaccess, limitcheck, rangecheck, stackunderflow, typecheck 


% interpret userpath 
% save CTM 
% concat matrix to CTM 

% restore original CTM 


25 A more satisfactory emulation of ustrokepath would not create a new matrix 
each time but would define one temporary matrix that it reuses. 
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viewclip - viewclip - 


viewclippath 


replaces the current view clipping path by a copy of the current path in 
the graphics state. The inside of the current path is determined by the 
normal non-zero winding number rule, viewclip implicitly closes any 
open subpaths of the view clipping path. After setting the view clip, 
viewclip resets the current path to empty, as if by newpath. 

viewclip is similar to clip in that it causes subsequent painting opera¬ 
tions to affect only those areas of the current page that lie inside the 
new view clip path. However, it differs from clip in three important 
respects: 

• The view clipping path is independent of the current clipping 
path. The current clipping path is unaffected; a subsequent 
clippath returns the current clipping path, uninfluenced by the 
additional clipping imposed by the view clip. 

• viewclip entirely replaces the current view clipping path, whereas 
clip computes the intersection of the current and new clipping 
paths. 

• viewclip performs an implicit newpath at the end of its execu¬ 
tion, whereas clip leaves the current path unchanged. 

The view clipping path can be described by a user path (see Section 8); 
this is accomplished by: 

newpath userpath uappend viewclip 

If userpath specifies ucache, this operation may take advantage of 
information in the user path cache. 

ERRORS: 

limitcheck 


- viewclippath - 

replaces the current path by a copy of the current view clip path. If no 
view clipping path has been set, viewclippath replaces the current path 
by one that encloses the entire imageable area of the output device (see 
initviewclip). 

ERRORS: (none) 
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vmreclaim int vmreclaim - 


controls the garbage collection machinery as specified by int : 

-2 disable automatic collection in both private and shared VM. 
-1 disable automatic collection in private VM. 

0 enable automatic collection. 

1 perform immediate collection in private VM. 

2 perform immediate collection in both private and shared 
VM. This can take a long time, since it must consult the 
private VMs of all contexts. 

Garbage collection causes the memory occupied by the values of in¬ 
accessible objects to be reclaimed and made available for re-use. It 
does not have any effects that are visible to the PostScript language 
program. There is normally no need to execute the vmreclaim 
operator, since garbage collection is invoked automatically when 
necessary. However, there are a few situations in which this operator 
may be useful: 

• In an interactive application that is temporarily idle, the idle time 
can be put to good use by invoking an immediate garbage collec¬ 
tion; this defers the need to perform an automatic collection sub¬ 
sequently. 

• When monitoring the VM consumption of a program, one must 
invoke garbage collection before executing vmstatus in order to 
obtain meaningful results. 

• When measuring the execution time of a program, one must dis¬ 
able automatic garbage collection in order to obtain repeatable 
results. 

The negative values that disable garbage collection apply only to the 
current context; that is, they do not prevent collection from occurring 
during execution of other contexts. Note that disabling garbage collec¬ 
tion for too long may eventually cause a program to run out of memory 
and fail with a VMerror. 

ERRORS: 

rangecheck, stackunderflow, typecheck 


16 OPERATORS 


129 



vmstatus - vmstatus level used maximum 


returns information about the state of the VM, as described in the 
PostScript Language Reference Manual. However, in the Display 
PostScript system, the returned values have more complex interpreta¬ 
tions. 

VM consumption is monitored separately for private and shared VM. 
The used and maximum values apply to either private or shared VM 
according to the current VM allocation mode (see setshared). Ad¬ 
ditionally, since save and restore do not have any effect on shared VM, 
the level value is meaningless if the current VM allocation mode is 
shared. 

The used value is meaningful only immediately after a garbage collec¬ 
tion has taken place (see vmreclaim). At other times, it may be too 
large because it includes memory occupied by objects that have be¬ 
come inaccessible but have not yet been reclaimed. 

The maximum value reflects the maximum prior memory consumption 
by the VM region in question. It is not necessarily a limit, since the 
Display PostScript system can usually obtain more memory dynami¬ 
cally from the underlying operating system. However, because of 
memory fragmentation it may not be possible to allocate an array or 
string whose size is maximum - used. In an environment that supports 
multiple PostScript execution contexts, available memory can be real¬ 
located from one context’s VM to another. 

ERRORS: 

stackoverflow 
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wait lock condition wait - 


releases lock , waits for condition to be notified (by some other context), 
and finally reacquires lock. The lock must originally have been ac¬ 
quired by the current context, which means that wait can be invoked 
only within the execution of a monitor that references the same lock. 

If lock is initially held by some other context or is not held by any 
context, wait executes an invalidcontext error. On the other hand, 
during the wait for condition , the lock can be acquired by some other 
context. After condition is notified, wait will wait arbitrarily long to 
reacquire lock. 

If the current context has previously executed a save not yet matched 
by a restore, wait executes invalidcontext unless both lock and 
conditional in shared VM. The latter case is permitted under the as¬ 
sumption that the wait is synchronizing with some context whose space 
is different from that of the current context. 

ERRORS: 

invalidcontext, stackunderflow, typecheck 


writeobject file obj tag writeobject - 

writes a binary object sequence to file. Except for taking an explicit file 
operand, writeobject is identical to printobject in all respects. 

As is the case for all operators that write to files, the output produced 
by writeobject may accumulate in a buffer instead of being transmitted 
immediately. To ensure immediate transmission, a flushfile is required. 

ERRORS: 

invalidaccess, ioerror, limitcheck, rangecheck, stackunderflow, 
typecheck, undefined 
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wtranslation - wtranslation xy 

returns the translation from the window origin to the PostScript device 
space origin. The integers x and y are the amounts that need to be added 
to a window system coordinate to produce the PostScript device space 
coordinate for the same position. That coordinate may in turn be trans¬ 
formed to user space by the itransform operator. 

Window system and device space coordinates always correspond in 
resolution and orientation; they differ only in the positions of their 
origins. The translation from one origin to the other may change as 
windows are moved and resized; the precise behavior is window sys¬ 
tem specific. 

ERRORS: 

stackoverflow 


xshow text numarray xshow - 
text numstring xshow - 


is similar to xyshow. However, for each character shown, xshow ex¬ 
tracts only one number from numarray or numstring ; it uses that num¬ 
ber as the x displacement and the value zero as the y displacement. In 
all other repects, xshow behaves the same as xyshow. 

ERRORS: 

invalidaccess, invalidfont, nocurrentpoint, rangecheck, 
stackunderflow, typecheck 
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xyshow text numarray xyshow - 
text numstring xyshow - 

prints successive characters of text in a manner similar to show. After 
rendering each character, it extracts two successive numbers from the 
array numarray or the encoded number string numstring. These two 
numbers, interpreted in user space, determine the position of the origin 
of the next character relative to the origin of the character just shown. 
The first number is the x displacement and the second number is the y 
displacement. In other words, the two numbers override the character’s 
normal width. 

If numarray or numstring is exhausted before all the characters of text 
have been shown, a rangecheck error will occur. 

ERRORS: 

invalidaccess, invalidfont, nocurrentpoint, rangecheck, 
stackunderflow, typecheck 

yield - yield - 

suspends the current context until all other contexts sharing the same 
space have had a chance to execute. This should not be used as a 
synchronization primitive, since there is no way to predict how much 
execution the other contexts will be able to accomplish. The purpose of 
yield is to break up long-running computations that might lock out 
other contexts. 

ERRORS: 

(none) 
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yshow text numarray yshow - 
text numstring yshow - 


is similar to xyshow. However, for each character shown, yshow ex¬ 
tracts only one number from numarray or numstring ; it uses that num¬ 
ber as the y displacement and the value zero as the x displacement. In 
all repects, it behaves the same as xyshow. 

text is the string that specifies what characters are to be shown (as in 
show), numarry is an array whose elements are all numbers, numstring 
is an encoded number string, constructed as described in Section 2. 

ERRORS: 

invalidaccess, invalidfont, nocurrentpoint, rangecheck, 
stackunderflow, typecheck 
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A CHANGES SINCE LAST PUBLICATION OF THIS DOCUMENT 


The changes to PostScript Language Extensions for the Display 
PostScript System from the document dated October 25, 1989, 
are noted in the paragraphs below. 

The definefont operator, which was missing from the Operator 
Summary, has been added. 

Minor amplifications and corrections, including changes in pos¬ 
sible errors, have been made to the following operators: 
definefont, currenthalftone, rectstroke, setcacheparams, 
setgstate, setfileposition, sethalftone, setucacheparams, 
ucache, upath. 

There are similar amplifications and corrections throughout the 
manual. 

The index has been enhanced. 

The changes to PostScript Language Extensions for the Display 
PostScript System from the document dated May 30, 1989, are 
noted in the paragraphs below. 

The quit operator has been added to Section 16, and differences 
from its description in the PostScript Language Reference 
Manual have been provided. 

The detach and vmstatus operators, which were missing from 
the Operator Summary, have been added. 

The setbbox operator description has been amplified. 

The changes to PostScript Language Extensions for the Display 
PostScript System from the document dated October 6, 1988, are 
noted in the paragraphs below. 

The header of binary object sequences has been extended to al¬ 
low binary object sequences with more than 255 top-level ob¬ 
jects. The header may have four or eight characters of informa¬ 
tion. See Binary Object Sequences in Chapter 2, Alternative 
Language Encodings. 

Management of user objects is system specific and may not be 
performed by the Client Library. 
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Three keys have been added to the top level font dictionary to 
control the difference in appearance between hand-tuned bitmaps 
and scan-converted outlines for characters (ExactSize, 
InBetweenSize, and TransformedChar). See Outline and Bit¬ 
map Font Coordination in Chapter 10, Font Related Extensions. 

The dictionary stack has been changed to add a third permanent 
entry: shareddict. Originally, this stack contained only two per¬ 
manent entries, systemdict and userdict. 

In Appendix C, System Name Encodings, values 372-428 have 
been changed and values 429-603 have been deleted. 

Changes to operators summarized below are documented in full 
in Chapter 16, Operators. 

cleardictstack is a new operator that pops all nonpermanent dic¬ 
tionaries off the dictionary stack. 


currentscreen has been extended to return the current halftone 
screen unless sethalftone was used, in which case it returns the 
current halftone dictionary. Previously, currentscreen returned a 
result that depended upon the halftone dictionary type. 


fork gives a forked context the objectformat of the current con¬ 
text. 


ineofill, given a userpath argument, tests whether pixels in 
userpath would be painted by eofill. 

infill, given a userpath argument, tests whether pixels in 
userpath would be painted by fill. 

instroke, given a userpath argument, tests whether pixels in 
userpath would be painted by stroke. 

inueofill now has a form that tests whether pixels in userpath 1 
would be painted by ueofill of userpath 2 . 

inufill now has a form that tests whether pixels in userpath] 
would be painted by ufill of userpath 2 . 

inustroke now has a form that tests whether pixels in userpathj 
would be painted by ustroke of userpath 2 . 
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printobject can now write an array that contains an element of 
type array. Previously, this was not permissible. 

rectstroke has an optional matrix argument. 

setcacheparams now takes a size argument. 

setscreen has been extended to take either a halftone dictionary 
or a spot function procedure as its third argument. 

writeobject can now write an array that contains an element of 
type array. Previously, this was not permissible. 
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B POSTSCRIPT LANGUAGE CHANGES 


Several additions have been made to the standard PostScript lan¬ 
guage. These additions are upward-compatible and do not affect 
the function of any existing PostScript language programs. The 
changes are included in all PostScript language implementations 
with version number 25.0 or higher; they are documented in edi¬ 
tions of the PostScript Language Reference Manual copyright 
1986 or later. 

In general, PostScript language programs that are intended to be 
compatible with all PostScript printers should not make use of 
the new features. However, it is possible for a program to deter¬ 
mine whether or not the new features are present and to invoke 
them conditionally. The descriptions below suggest how to 
determine whether a particular feature is present or absent. 

Packed arrays 

PostScript language procedures are represented as executable ar¬ 
rays which, until now, have been stored in the same fashion as 
literal data arrays. This representation, while offering maximum 
flexibility, is very costly in space (8 bytes per element). Large 
PostScript language programs, such as the built-in server 
program and downloaded preambles, consume considerable 
amounts of VM. 

Since most programs do not require the ability to be treated as 
data but only the ability to be executed, a more compact repre¬ 
sentation has been introduced: the packed array. Programs 
represented as packed arrays are typically 50 to 75 percent 
smaller than the same programs represented as ordinary arrays. 

A packed array object has a type different from an ordinary array 
object (‘packedarraytype’ versus ‘arraytype’); but in most 
respects it behaves the same as an ordinary array. You can ex¬ 
ecute a packed array; you can extract elements (using get) or 
subarrays (using getinterval); you can enumerate it (using 
forall); and so forth. Individual elements extracted from a 
packed array are ordinary PostScript objects; a subarray of a 
packed array is also a packed array. 
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The differences between packed arrays and ordinary arrays are: 

• Packed arrays are always read-only: you can’t use put, 
putinterval, etc., to store into one. 

• Packed arrays are created differently from ordinary arrays 
(see below). 

• Accessing arbitrary elements of a packed array can be quite 
slow; however, accessing the elements sequentially (as is 
done by the PostScript interpreter and by the forall 
operator) is approximately as efficient as accessing an or¬ 
dinary array. 

• The copy operator cannot copy into a packed array (since it 
is read-only); however, it can copy the value of a packed 
array to an ordinary array of at least the packed array’s 
length. 

There are two ways in which packed arrays come into existence. 
The first and more common way is for the PostScript input 
scanner to create packed arrays automatically for all executable 
arrays that it reads. That is, whenever the scanner encounters a 
‘{’ while reading a file or string, it accumulates all tokens up to 
the matching *}’ and turns them into a packed array instead of an 
ordinary array. 

The choice of array type is controlled by a mode setting, manipu¬ 
lated by the new operators setpacking and currentpacking 
(described at the end of this section). If the array packing mode 
is true, PostScript language procedures encountered sub¬ 
sequently by the scanner are created as packed arrays; if the 
mode is false, procedures are created as ordinary arrays. The 
default value is false (i.e., create ordinary arrays), for com¬ 
patibility with existing programs. 

The other way to create a packed array is to build it explicitly by 
invoking the packedarray operator with a list of operands to be 
incorporated into a new packed array. 

Immediately evaluated names 

The language syntax has been extended to include a new kind of 
name token, the immediately evaluated name. When the scanner 
encounters the token d/name ’ (a name preceded by two slashes 
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with no intervening spaces), it immediately looks up the name in 
the context of the current dictionary stack and substitutes the cor¬ 
responding value for the name. If the name is not found, an 
undefined error occurs. 

The substitution occurs immediately, regardless of whether or not 
the token appears inside an executable array delimited by ‘{...}\ 
Note that this process is a substitution and not an execution; that 
is, the name’s value is not executed but rather is substituted for 
the name itself, just as if the load operator had been applied to 
the name. This action is related to the action performed by the 
bind operator (see the PostScript Language Reference Manual)', 
but whereas bind performs substitution only for names whose 
values are operators, each occurrence of the ‘ llname ’ syntax is 
replaced by the value associated with name regardless of the 
value’s type. The following examples illustrate this: 

/a 3 def 

/b {(test) print} def 
//a => 3 

//b => {(test) print} 

{//a //b a /b} => {3 {(test) print} a lb) 

The purpose of using immediately evaluated names is similar to 
that of using the bind operator: to cause names in procedures to 
become ‘tightly bound’ to their values. However, a word of cau¬ 
tion is in order: indiscriminate use of immediately evaluated 
names may change the semantics of a program. In particular, 
recall that when the interpreter encounters a procedure object 
directly it simply pushes it on the operand stack; but when it 
encounters a procedure object indirectly (by looking up an ex¬ 
ecutable name) it executes the procedure. (See Section 3.6 of the 
PostScript Language Reference Manual.) Therefore, execution 
of the program fragments: 

{- b...} 

{... //b ...} 

may have different effects if the value of the name ‘b’ is a proce¬ 
dure. 

The immediately evaluated name facility is present in all ver¬ 
sions of the PostScript interpreter since version 25.0 (as reported 
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by the version operator). Earlier versions of the interpreter will 
scan 7 /name’ as two distinct tokens: 7’, a literal name with no 
text at all, and 7 name ', a literal name whose text is name. 
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New Operators 


setpacking 


currentpacking 


bool setpacking - 

sets the array packing mode to the specified boolean value. This deter¬ 
mines the type of executable arrays subsequently created by the scan¬ 
ner. The value true selects packed arrays \ false selects ordinary arrays. 

The packing mode affects only the creation of procedures by the scan¬ 
ner when it encounters program text bracketed by ‘{’ and *}’ during 
interpretation of an executable file or string object or during execution 
of the token operator. It does not affect the creation of literal arrays by 
the ‘[’ and *]’ operators or by the array operator. 

The array packing mode setting persists until overridden by another 
execution of setpacking or until undone by a restore. 

EXAMPLE: 

systemdict /setpacking known 
{/savepacking currentpacking def 
true setpacking 

} if 

... arbitrary procedure definitions ... 

systemdict /setpacking known {savepacking setpacking} if 

If the packed array facility is available, the procedures represented by 
‘arbitrary procedure definitions’ are defined as packed arrays; other¬ 
wise they are defined as ordinary arrays. This example is careful to 
preserve the array packing mode in effect before its execution. 

ERRORS: 

stackunderflow, typecheck 


- currentpacking bool 

returns the array packing mode currently in effect. 

STANDARD VALUE: false 

ERRORS: 

stackoverflow 
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packedarray any 0 ... any n _ 1 n packedarray packedarray 

creates a packed array object of length n containing the objects any 0 
through as elements, packedarray first removes the non¬ 

negative integer n from the operand stack. It then removes that number 
of objects from the operand stack, creates a packed array containing 
those objects as elements, and finally pushes the resulting packed array 
object on the operand stack. 

The resulting object has a type of ‘packedarraytype’, a literal attribute, 
and read-only access. In all other respects, its behavior is identical to 
that of an ordinary array object. 

STANDARD VALUE: false 

ERRORS: 

rangecheck, stackunderflow, typecheck, VMerror 
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showpage and copypage 


The correct use of showpage versus copypage is a matter requir¬ 
ing some clarification. Inappropriate use of copypage can result 
in significant performance degradation in new PostScript 
printers. 

showpage is the normal operator for causing pages to be output. 
It has three effects: it prints the current page, it erases the current 
page, and it reinitializes the graphics state. 

copypage is a somewhat more specialized operator that just 
prints the current page but does not erase it or reset the graphics 
state. Its main intended use is to permit adding new marks to an 
existing page, e.g., when building up a page incrementally. 

showpage is logically equivalent to the sequence: 

copypage erasepage initgraphics 

However, use of copypage for printing pages can degrade page 
throughput significantly. One reason for this is that showpage 
performs the printing and the erasing in parallel whereas the 
copypage erasepage method performs them serially; there are 
other reasons as well. 

copypage should also not be used to defeat the automatic 
initgraphics of showpage . 1 That is, to print and erase the cur¬ 
rent page but leave the graphics state unchanged, you should not 
say: 


copypage erasepage 
Instead you should say: 

gsave showpage grestore 

Please also note that the correct way to print multiple copies of a 
page is to associate the desired number of copies with the name 
#copies prior to invoking showpage, as discussed under 
showpage in the PostScript Language Reference Manual. The 
#copies convention now applies uniformly to both showpage 
and copypage, whereas formerly it applied only to showpage. 

'Unfortunately, the current PostScript Language Tutorial and Cookbook in¬ 
cludes an example that uses this technique. 
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C SYSTEM NAME ENCODINGS 


index 

name 

index 

name 

index 

name 

0 

abs 

41 

currentrgbcolor 

82 

idiv 

1 

add 

42 

currentshared 

83 

idtransform 

2 

aload 

43 

curveto 

84 

if 

3 

anchorsearch 

44 

cvi 

85 

ifelse 

4 

and 

45 

cvlit 

86 

image 

5 

arc 

46 

cvn 

87 

imagemask 

6 

arcn 

47 

cvr 

88 

index 

7 

arct 

48 

cvrs 

89 

ineofill 

8 

arcto 

49 

CVS 

90 

infill 

9 

array 

50 

cvx 

91 

initviewelip 

10 

ashow 

51 

def 

92 

inueofill 

11 

astore 

52 

defineusemame 

93 

inufill 

12 

awidthshow 

53 

diet 

94 

invertmatrix 

13 

begin 

54 

div 

95 

itransform 

14 

bind 

55 

dtransform 

96 

known 

15 

bitshift 

56 

dup 

97 

le 

16 

ceiling 

57 

end 

98 

length 

17 

charpath 

58 

eoclip 

99 

lineto 

18 

clear 

59 

eofill 

100 

load 

19 

cleartomark 

60 

eoviewelip 

101 

loop 

20 

clip 

61 

eq 

102 

It 

21 

clippath 

62 

exch 

103 

makefont 

22 

closepath 

63 

exec 

104 

matrix 

23 

concat 

64 

exit 

105 

maxlength 

24 

concatmatrix 

65 

file 

106 

mod 

25 

copy 

66 

fill 

107 

moveto 

26 

count 

67 

findfont 

108 

mul 

27 

counttomark 

68 

flattenpath 

109 

ne 

28 

currentcmykcolor 

69 

floor 

110 

neg 

29 

currentdash 

70 

flush 

111 

newpath 

30 

currentdict 

71 

flushfile 

112 

not 

31 

currentfile 

72 

for 

113 

null 

32 

currentfont 

73 

forall 

114 

or 

33 

currentgray 

74 

ge 

115 

pathbbox 

34 

currentgstate 

75 

get 

116 

pathforall 

35 

currenthsbcolor 

76 

getinterval 

117 

pop 

36 

currentlinecap 

77 

grestore 

118 

print 

37 

currentlinejoin 

78 

gsave 

119 

printobject 

38 

currentlinewidth 

79 

gstate 

120 

put 

39 

currentmatrix 

80 

gt 

121 

putinterval 

40 

currentpoint 

81 

identmatrix 

122 

rcurveto 
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123 

read 

167 

stroke 

211 

124 

readhexstring 

168 

strokepath 

212 

125 

readline 

169 

sub 

256 

126 

readstring 

170 

systemdict 

257 

127 

rectclip 

171 

token 

258 

128 

rectfill 

172 

transform 

259 

129 

rectstroke 

173 

translate 

260 

130 

rectviewclip 

174 

truncate 

261 

131 

repeat 

175 

type 

262 

132 

restore 

176 

uappend 

263 

133 

rlineto 

177 

ucache 

264 

134 

rmoveto 

178 

ueofill 

265 

135 

roll 

179 

ufill 

266 

136 

rotate 

180 

undef 

267 

137 

round 

181 

upath 

268 

138 

save 

182 

userdict 

269 

139 

scale 

183 

ustroke 

270 

140 

scalefont 

184 

viewelip 

271 

141 

search 

185 

viewelippath 

272 

142 

selectfont 

186 

where 

273 

143 

setbbox 

187 

widthshow 

274 

144 

setcachedevice 

188 

write 

275 

145 

setcachedevice2 

189 

writehexstring 

276 

146 

setcharwidth 

190 

writeobject 

277 

147 

setcmykcolor 

191 

writestring 

278 

148 

setdash 

192 

wtranslation 

279 

149 

setfont 

193 

xor 

280 

150 

setgray 

194 

xshow 

281 

151 

setgstate 

195 

xyshow 

282 

152 

sethsbcolor 

196 

yshow 

283 

153 

setlinecap 

197 

FontDirectory 

284 

154 

setlinejoin 

198 

SharedFontDirectory 

285 

155 

setlinewidth 

199 

Courier 

286 

156 

setmatrix 

200 

Courier-Bold 

287 

157 

setrgbcolor 

201 

Courier-BoldOblique 

288 

158 

setshared 

202 

Courier-Oblique 

289 

159 

shareddict 

203 

Helvetica 

290 

160 

show 

204 

Helvetica-Bold 

291 

161 

showpage 

205 

Helvetica-BoldOblique 

292 

162 

stop 

206 

Helvetica-Oblique 

293 

163 

stopped 

207 

Symbol 

294 

164 

store 

208 

Times-Bold 

295 

165 

string 

209 

Times-Boldltalic 

296 

166 

stringwidth 

210 

Times-Italic 

297 
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Times-Roman 

execuserobject 

ISOLatin 1 Encoding 
StandardEncoding 
[ 

] 

atan 

banddevice 

bytesavailable 

cachestatus 

closefile 

colorimage 

condition 

copypage 

cos 

countdictstack 

countexecstack 

cshow 

currentblackgeneration 

currentcacheparams 

currentcolorscreen 

currentcolortransfer 

currentcontext 

currentflat 

currenthalftone 

currenthalftonephase 

currentmiterlimit 

currentobjectformat 

currentpacking 

currentscreen 

currentstrokeadj ust 

currenttransfer 

currentundercolorremoval 

defaultmatrix 

definefont 

deletefile 

detach 

deviceinfo 

diets tack 

echo 

erasepage 

errordict 
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execstack 

342 

setfileposition 

386 

299 

executeonly 

343 

setflat 

387 

300 

exp 

344 

sethalftone 

388 

301 

false 

345 

sethalftonephase 

389 

302 

filenameforall 

346 

setmiterlimit 

390 

303 

fileposition 

347 

setobjectformat 

391 

304 

fork 

348 

setpacking 

392 

305 

framedevice 

349 

setscreen 

393 

306 

grestoreall 

350 

setstrokeadjust 

394 

307 

handleerror 

351 

settransfer 

395 

308 

initclip 

352 

setucacheparams 

396 

309 

initgraphics 

353 

setundercolorremoval 

397 

310 

initmatrix 

354 

sin 

398 

311 

instroke 

355 

sqrt 

399 

312 

inustroke 

356 

srand 

400 

313 

join 

357 

stack 

401 

314 

kshow 

358 

status 

402 

315 

In 

359 

statusdict 

403 

316 

lock 

360 

true 

404 

317 

log 

361 

ucachestatus 

405 

318 

mark 

362 

undefinefont 

406 

319 

monitor 

363 

usertime 

407 

320 

noaccess 

364 

ustrokepath 

408 

321 

notify 

365 

version 

409 

322 

nulldevice 

366 

vmreclaim 

410 

323 

packedarray 

367 

vmstatus 

411 

324 

quit 

368 

wait 

412 

325 

rand 

369 

wcheck 

413 

326 

rcheck 

370 

xcheck 

414 

327 

readonly 

371 

yield 

415 

328 

realtime 

372 

defineuserobject 

416 

329 

renamefile 

373 

undefineuserobject 

417 

330 

renderbands 

374 

UserObjects 

418 

331 

resetfile 

375 

cleardictstack 

419 

332 

reversepath 

376 

A 

420 

333 

rootfont 

377 

B 

421 

334 

rrand 

378 

C 

422 

335 

run 

379 

D 

423 

336 

scheck 

380 

E 

424 

337 

setblackgeneration 

381 

F 

425 

338 

setcachelimit 

382 

G 

426 

339 

setcacheparams 

383 

H 

427 

340 

setcolorscreen 

384 

I 

428 

341 

setcolortransfer 

385 

J 
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Rich Text Format 


The Rich Text Format (RTF) standard is a method of encoding formatted text and 
graphics for easy transfer between applications. Currently, users depend on special 
translation software to move word-processing documents between different DOS 
and OS/2 applications, and between DOS or OS/2 applications and Apple Macin¬ 
tosh applications. 

The RTF standard provides a format for text and graphics interchange that can 
be used with different output devices, operating environments, and operating 
systems. RTF uses the ANSI, PC-8, Macintosh, or IBM PC character set to control 
the representation and formatting of a document, both on the screen and in print 
With the RTF standard, documents created under different operating systems and 
with different software applications can be transferred among those operating 
systems and applications. 

Software that takes a formatted file and turns it into an RTF file is called a 
writer. Software that translates an RTF file into a formatted file is called a reader. 
An RTF writer separates the application’s control information from the actual text 
and writes a new file containing the text and the RTF groups associated with that 
text An RTF reader does the converse of this procedure. 

RTF SYNTAX 

An RTF file consists of unformatted text, control words, control symbols, and 
groups. For ease of transport, a standard RTF file consists of only 7-bit ASCII 
characters. 
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A group consists of text and control words or control symbols enclosed in 
braces ({ }). The opening { indicates the start of the group and the closing } 
indicates the end of the group. Each group specifies the text affected by the group 
and the different attributes of that text. The RTF file can also include groups for 
fonts, styles, screen color, pictures, footnotes, annotations, headers and footers, 
summary information, fields, and bookmarks, as well as document-, section-, 
paragraph-, and character-formatting properties. If the font, style, screen-color, 
and summary-information groups and document-formatting properties are in¬ 
cluded, they must precede the first plain-text character in the document These 
groups form the RTF file header. If the group for fonts is included, it should precede 
the group for styles. If any group is not used, it can be emitted. The groups are 
discussed in the following sections. 

Certain control words control properties (such as bold, italic, keep together, 
and so forth) that have only two states. When such a control word has no parameter 
or has a nonzero parameter, it is assumed that the control word turns on the 
property. When such a control word has a parameter of 0 (zero), it is assumed that 
the control word turns off the property. For example, \b turns on bold, whereas \b0 
turns off bold. 

Certain control words, referred to as destinations, mark the beginning of a 
collection of related text. An example of a destination is the\footnote group, where 
the footnote text follows the control word. Destination control words and their 
following text must be enclosed in braces. Destinations added after the RTF 
specification published in the March 1987 Microsoft Systems Journal may be 
preceded by the control symbol \*. This control symbol identifies destinations 
whose related text should be ignored if the RTF reader does not recognize the 
destination. (RTF writers should follow the convention of using this control 
symbol when adding new control words.) Destinations whose related text should 
be inserted into the document even if the RTF reader does not recognize the 
destination should not use \*. In this chapter, all destinations that were not included 
in the March 1987 RTF specification are shown with\* as part of the control word. 

Formatting specified within a group affects only the text within that group. 
Generally, text within a group inherits the formatting of the text in the preceding 
group. However, Microsoft implementations of RTF assume that the footnote, 
header and footer, and annotation groups (described later in this chapter) do not 
inherit the formatting of the preceding text. Therefore, to ensure that these groups 
are always formatted correctly, you should set the formatting within these 
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■ Section-formatting properties, such as the number of columns. 

■ Table-formatting properties, which define the number of cells and 
dimensions of a table row. 

In practice, an RTF reader will proceed as follows: 

1. The reader reads the next character. 

2. If the character is an opening {, the reader stores the current state cm 
the stack. 

If the character is a closing }, the reader retrieves the current state 
from the stack. 

If the character is a backslash, the reader collects the control word 
or control symbol and its parameter, if any, and looks up the control 
word or control symbol in a table. It then carries out the action 
prescribed in the table. (The possible actions are discussed below.) The 
read pointer is left before or after a control-word delimiter, as appro¬ 
priate. 

If the character is anything other than {,}, or\ the reader assumes 
that the character is plain text and writes the character to the current 
destination using current formatting properties. 

3. The reader then reads the next character. 

If the RTF reader cannot find a particular control word or control symbol in 
the look-up table, the control word or control symbol should be ignored. If a 
control word or control symbol is preceded by an opening {, it is part of a group. 
The current state should be saved on the stack, but no state change should occur. 
When a closing } is encountered, the current state should be retrieved from the 
stack, thereby resetting the current state. If the \* control symbol precedes a control 
word, then it defines a destination group and was itself preceded by an opening {. 
The RTF reader should discard all text up to and including the } that closes 
this group. 

For control words or control symbols that the RTF reader can find in the 
look-up table, the possible actions are as follows. 
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Control word 

Character set 

\ansi 

ANSI (default) 

\mac 

Apple Macintosh 

\pc 

IBM PC 

\pca 

IBM PC page 850, used by IBM Personal System/2 (not 
implemented in version 1 of Word for OS/2) 

The Font Table 


This group begins with the control word \fonttbI and contains descriptions of 
fonts. All fonts available to the RTF writer can be included in the font table, even 
if the document doesn’t use all the fonts. 

A font is defined by a font number, a font family, and a font name as shown 

in the following example: 


ABC D 

111_1 


i i i i i 

{Vfontttol\fO\fromanTms Rmn;}.. 

A Control word C 

Font family 

B Font number D 

Font name 

Semicolons separate one font from the next. The font numbers represent the full font 

definitions in the group and vary with each document The font families are listed below: 

Control word 

Font family 

\fnil 

Unknown or default fonts (default) 

\f roman 

Roman, proportionally spaced serif fonts (Tms Rmn, 
Palatino, etc.) 

\fswiss 

Swiss, proportionally spaced sans serif fonts (Swiss, etc.) 

\fmodcrn 

Fixed-pitch serif and sans serif fonts (Courier, Pica, etc.) 

\fscript 

Script fonts (Cursive, etc.) 

\fdecor 

Decorative fonts (Old English, ITC Zapf Chancery, etc.) 

\ftech 

Technical, symbol, and mathematical fonts (Symbol, etc.) 


If an RTF file uses a default font, the default font number is specified with the 
\deffrz control word, which must precede the font-table group. The RTF writer 
supplies the default font number used in the creation of the document as the 
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In this example, PostScript is declared but not used. Some of the control words in 
this example are discussed in the following sections. 

The Color Table 

Screen colors, character colors, and other color information are contained in the 
color-table group. The control word\colortbI begins this group. Additional control 
words for red, green, and blue and the foreground and background colors then use 
parameter values (0-255) corresponding to the color indexes used by Microsoft 
Windows to define the amount of red, green, and blue that makes up a color. For 
more information on color setup, see your Windows documentation. 

The following are valid control words for this group: 


Control word 

Meaning 

\redn 

Red index 

\greenn 

Green index 

\bluen 

Blue index 

\cfn 

Foreground color (default is 0) 

\cbn 

Background color (default is 0) 


Each definition must be delimited by a semicolon, even if the definition is 
omitted. If a color definition is omitted, the RTF reader uses its default color. In 
the example below, three colors are defined. The first color is omitted, as shown 
by the semicolon following the \colortbI control word. 


{\oolortblAredO\greenO\blueOAredOVgreenO\blue255;} 

The following example defines a block of text in color (where supported). 
Note that the cf/cb index is the index of an entry in the color table, which represents 
a red/green/blue color combination. 


{Yf1Vcb1Vcrf2 This is colored text. The background is color 
1 and the foreground Is oolor 2.) 


If the file is translated for software that does not display color, the reader 
ignores the color-table group. 
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Continued 


Control word 

Meaning 

\piccroptn 

Top cropping value in twips; a positive value crops toward 
the center of die picture; a negative value crops away from 
the center, adding a space border around picture (default is 0). 

\piccroptm 

Bottom cropping value in twips; a positive value crops 
toward the center of the picture; a negative value crops 
away from the center, adding a space border around 
picture (default is 0). 

\piccroplrt 

Left cropping value in twips; a positive value crops toward 
the center of die picture; a negative value crops away from 
the center, adding a space border around picture (default is 0). 

\piccropm 

Right cropping value in twips; a positive value crops 
toward the center of the picture; a negative value crops 
away from the center, adding a space border around 
picture (default is 0). 

Wbmbltspixeln 

Number of bitmap bits/pixel (default is 1). 

Wbmplanesn 

Number of bitmap planes (default is 1). 

\wbmwidthbytesn 

Bitmap width in bytes. 

xbinn 

Picture is in binary format; the numeric parameter n is the 
number of bytes that follow. 

The control words for picture border patterns (\brdrs, \brdrdb, \brdrth, 
\brdrsh, \brdrdot, and \brdrhair) are ignored when translating into Microsoft 
Word for the Macintosh, which uses character properties to make borders. 

The\wbitmap control word is optional; if neither Wmetafile nor \macpict 
is specified, the picture is assumed to be a Windows bitmap. If Wmetafile is 
specified, the n argument can be one of the following types: 

Type 

rt argument 

MMJTEXT 

1 

MM_LOMETRIC 

2 

MM_HIMETRIC 

3 

MM_LOENGUSH 

4 

MM_HIENGLISH 

5 

MMTWIPS 

6 

MMJSOTROPIC 

7 

MM_ANISOTROPIC 

8 
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And here’s the result: 



Footnotes 

The group containing footnote text begins with the control word \*\footnote. 
Footnotes are anchored to the character that immediately precedes the footnote 
group. If automatic footnoting is defined, the group can be preceded by a 
footnote reference character, identified by the control word \chftn. 

On the next page is an example of a group containing footnotes. 
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Headers and Footers 

Headers and footers are treated as separate groups in RTF. Different headers and 
footers can be defined for different sections in the document. If none is defined 
for a given section, the headers and footers from the previous section (if any) are 
used. These groups must precede the first plain-text character in the document 
section to which they apply. 

The control words \header and \footer begin these groups. These control 
words can be replaced by the following control words, as appropriate: 


Control word 

Meaning 

\headerl 

Header on left pages only 

\headerr 

Header on right pages only 

\headerf 

Header on first page only 

\footerl 

Footer on left pages only 

\footerr 

Footer on right pages only 

\footerf 

Footer on first page only 


The \header! and Vheaderr and 'footer! and \footerr control words are used 
in conjunction with the \facingp control word, and the Mieaderf and \footerf 
control words are used in conjunction with the \titlepg control word. For more 
information, see “Document-Formatting Properties,” later in this chapter. 

Information 

The RTF file can also contain an information group, which is translated but not 
displayed with the text. This information can include the title, author, keywords, 
comments, and other information specific to the file. This information is for use 
by a document-management utility, if available. 

This group begins with the control word \info. Some applications, such as 
Word, ask a user to type this information when saving the document in its native 
format If the document is then saved as an RTF file or translated into RTF, the 
RTF writer specifies this information using the following control words. These 
control words are destinations and both the control words and the text should be 
enclosed in braces ({ }). 
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The Panda's Thumb}{\au1hor Stephen J. Gould}{\keywords 
science natural history}} 

Fields 

The field group contains the text of Word fields. For more detailed information on 
fields, see Chapter 9, “Fields.” 

The field group begins with the control word \field. These control words can 
follow the \field control word: 


Control word 

Meaning 

\flddirty 

Formatting change has been made to the field result since 
the field was last updated. 

\fldedit 

Text has been added to, or removed from, the field result 
since the field was last updated. 

\fldlock 

Field is locked and cannot be updated. 

\fldpriv 

Result is not in a form suitable for display (for example, 
binary data used by fields whose result is a picture). 

Two subgroups are available within the \field group. They must be enclosed 
in braces ({ }) and begin with the following control words: 

Control word 

Meaning 

\*\fldinst 

Field instructions 

\fidrslt 

Most recent calculated result of the field 


The \fldrslt control word should be included even if no result has been 
calculated, because even readers that do not recognize fields can generally include 
the value of the \fldrslt group in the document. 

An example of some field text follows: 

ABC 

i- ^ i i- ^ -11- 1 -1 

(\field\tldedrt{Vfldinst author}(\f!drsft Joe Smrth}}\par \pard 
{\field{\fldinst time \\@ M h:mm AM/PM"}{Vfldrslt 8:1 2 AM}} 

T 1 -1-“—i— 1 

A B C 

A Beg ins field group 
B Field instructions 
C Field result 
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Control word 

Meaning 

\tcfrt 

Type of table being compiled; n is mapped by existing 
Microsoft software to a letter between A and Z (default is 
67, which maps to C, used for tables of contents). 

\tcl/l 

Level number (default is 1). 


Bookmarks 

This group contains two control words: \*\bkmkstart, which indicates the start 
of the specified bookmark, and \*\bkmkend, which indicates the end of the 
specified bookmark. A bookmark is shown in the following example: 


\pard\plaln Vfs20 Kuhn believes that sdenoe. rather than 
discovering In experience certain structured 
relationships, actually creates (or already participates in) 
a presupposed structure to which It ms the data. 
{\bkmkstart paradigm)Kuhn oalls such a presupposed 
structure a paradlgm.{\bkmkend paradigm) 


Document-Formatting Properties 

This section specifies the attributes of the document, such as margins and footnote 
placement These attributes must precede the first plain-text character in the document 
The control words that specify document formatting are listed in the 
following table (measurements are in twips). For omitted control words, RTF 
uses the default values: 


Control word 

Meaning 

\paperwn 

Paper width (default is 12,240). 

\paperhn 

Paper height (default is 15,840). 

\margl/i 

Left margin (default is 1,800). 

\margrn 

Right margin (default is 1,800). 

\margtn 

Top margin (default is 1,440). 

\margbn 

Bottom margin (default is 1,440). 

\facingp 

Facing pages (activates odd/even headers and gutters). 

\guttern 

Gutter width (default is 0). 

\deftabn 

Default tab width (default is 720). 


(continued) 
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Section-Formatting Properties 

This group specifies section-formatting properties, which apply to the text 
following the control word, with the exception of the section-break control words 
(those beginning with \sbk). Section-break control words describe the break 
preceding the text. 

The section-formatting control words are listed in the following table: 


Control word 

Meaning 

\sectd 

Reset to default section properties. 

Vsbknone 

No section break. 

\sbkcol 

Section break starts a new column. 

\sbkpage 

Section break starts a new page (default). 

Vsbkeven 

Section break starts at an even page. 

\sbkodd 

Section break starts at an odd page. 

\pgnstartsn 

Beginning page number (default is 1). 

\pgncont 

Continuous page numbering (default). 

\pgnrestart 

Page numbers restart at \pgnstarts value. 

\pgndec 

Page-number format is decimal. 

\pgnucrm 

Page-number format is uppercase roman numeral. 

\pgnkrm 

Page-number format is lowercase roman numeral. 

\pgnudtr 

Page-number format is uppercase letter. 

\pgnlcltr 

Page-number format is lowercase letter. 

\pgnxn 

Page-number is n twips from die right margin (default is 720). 

\pgny n 

Page-number is n twips from the top margin (default is 720). 

\headery n 

Header is n twips from the top of the page (default is 720). 

\footeryn 

Footer is n twips from die bottom of the page (default is 720). 

\linemodn 

Line-number modulus-amount to increase each line 
number (default is 1). 

\Iinexn 

Distance from the line number to the left text margin in 
twips (default is 360). The automatic distance is 0. 

Minestartsn 

Beginning line number (default is 1). 

\Iinerestart 

Line numbers restart at \linestarts value. 

Mlneppage 

Line numbers restart on each page. 

\iinecont 

Line numbers continue from the preceding section. 

\vertalt 

Text is top-aligned (default). 


( continued) 
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Continued 


Control word 

Meaning 

\sln 

Space between lines: if this control word is missing or if 
\slOOO is used, the line spacing is automatically determined 
by the tallest character in the line; if n is a positive value, uses 
this size only if it is taller than the tallest character (otherwise 
uses the tallest character); if n is a negative value, uses die 
absolute value of n, even if it is shorter than the tallest 
character. 

Mntbl 

Paragraph is part of a table. 

\keep 

Keep paragraph intact 

\keepn 

Keep paragraph with the next paragraph. 

\sbys 

Side-by-side paragraphs. 

\pagebb 

Break page before the paragraph. 

\noIine 

No line numbering. 

\txn 

Tab position in twips from the left margin. 

\tqr 

Rush-right tab. 

\tqc 

Centered tab. 

\tqdec 

Decimal tab. 

\tbn 

Bar tab position in twips from the left margin. 

\brdrt 

Border top. 

\brdrb 

Border bottom. 

\brdrl 

Border left 

\brdrr 

Border right 

\brdrbar 

Border outside (right side of odd-numbered pages, left 
side of even-numbered pages). 

\box 

Border around the paragraph (box paragraph). 

\brdrs 

Single-thickness border. 

\brdrth 

Thick border. 

\brdrsh 

Shadowed border. 

\brdrdb 

Double border. 

\brdrdot 

Dotted border. 

\brdrhair 

Hairline border. 


(continued) 
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Rich Text Format 


Continued 

Control word 

Meaning 

\pvmrg 

Positions the paragraph vertically relative to the margin. 

\pvpg 

Positions the paragraph vertically relative to the page. 

\phmrg 

Positions the paragraph horizontally relative to the margin. 

\phpg 

Positions the paragraph horizontally relative to the page. 

\phcol 

Positions the paragraph horizontally relative to the column. 

The following is an example of absolute-positioned text in a document: 

A 


I-, 

Vpar Vpard \pvpg\phpg\posxc\posyt\absw5040\dxfrtext173 abs pos paral 
\par Vpard \phmrg\posxo\posyc\dxfrtext1152 abs pos para2^ 


A Text to be positioned 

A 

Tables 


There is no RTF table group. A table is a collection of paragraphs and a table row 
is a continuous sequence of paragraphs partitioned into cells. The\intbl paragraph¬ 
formatting control word identifies the paragraph as part of a table. The last 
paragraph of a cell is terminated by a cell mark (the \eell control word), and the 
row is terminated by a row mark (the Vow control word). The following control 
words further define the table: 

Control word 

Meaning 

\clbrdrb 

Bottom table cell border. 

\clbrdrt 

Top table cell border. 

\clbrdrl 

Left table cell border. 

\clbrdrr 

Right table cell border. 

\trowd 

Sets table row defaults. 

\trql 

Left-justifies a table row with respect to its containing 
column. 

\trqr 

Right-justifies a table row with respect to its containing 
column. 

\trqc 

Centers a table row with respect to its containing column. 

\trgaphrz 

Half the space between the cells of a table row in twips. 
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Rich Text Format 


The character-formatting control words are listed in the following table: 


Control word 

Meaning 

\plaln 

Resets application’s default character-formatting 
properties. 

\b 

Bold*. 

M 

Italic*. 

\strlke 

Strikethrough*. 

\outi 

Outline*. 

\shad 

Shadow*. 

\scaps 

Small capitals*. 

\caps 

All capitals*. 

\v 

Hidden text*. 

\fn 

Font number. 

\fsn 

Font size in half-points (default is 24). 

\expn dn 

Expansion or compression of the space between 
characters in quarter-points; a negative value compresses 
(default is 0). 

\ul 

Continuous underline*. 

Vulw 

Word underline*. 

\uld 

Dotted underline*. 

\uldb 

Double underline*. 

\ulnone 

Stops all underlining. 

\up n 

Superscript position in half-points (default is 6). 

\dn n 

Subscript position in half-points (default is 6). 

\re vised 

Text has been added since revision marking was turned on. 
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Rich Text Format 


Continued 


Control word 

Meaning 

Mdblquote 

Left double quotation mark. 

\rdblquote 

Right double quotation mark. 

M 

Formula character. 

\- 

Nonbreaking space. 

V 

Optional hyphen. 

\_ 

Nonbreaking hyphen. 

\: 

Specifies a subentry in an index entry. 

\* 

Marks a destination whose text should be ignored if not 
understood by the RTF reader. 

\’hh 

A hexadecimal value, based on the specified character set 
(may be used to identify 8-bit values). 


Note that an ASCII 9 is accepted as a tab character, and the code word 
\<ASCniO> (line feed) or \<ASCI113> (carriage return) is treated the same as 
the control word \par. You must include the backslashes or RTF ignores the control 
word. (You may also want to insert a carriage-retum/line-feed pair without 
backslashes at least every 255 characters for better text transmission over com¬ 
munication lines.) 

Here are the code values for the following special characters: 

ANSI 

Keyword (Word for Windows and OS/2) Apple Macintosh 


\bullet 

149 

0xA5 

Vemdash 

150 

OxDl 

\endash 

151 

OxDO 

\Iquote 

145 

0xD4 

\rquote 

146 

0xD5 

Mdblquote 

147 

0xD2 

\rdblquote 

148 

0xD3 
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